From efdb4cefb6d336f032bacb811eae735245ff514c Mon Sep 17 00:00:00 2001 From: Nadezhda Tacheva Date: Wed, 21 May 2025 16:29:34 +0300 Subject: [PATCH] chore(selects): Optimize reference documentation --- components/autocomplete/data-bind.md | 52 +----------------- components/autocomplete/overview.md | 4 +- components/combobox/data-bind.md | 60 +-------------------- components/combobox/overview.md | 3 +- components/dropdownlist/data-bind.md | 54 +------------------ components/dropdownlist/overview.md | 3 +- components/multicolumncombobox/data-bind.md | 2 +- components/multicolumncombobox/overview.md | 6 +-- components/multiselect/data-bind.md | 52 +----------------- components/multiselect/overview.md | 3 +- 10 files changed, 10 insertions(+), 229 deletions(-) diff --git a/components/autocomplete/data-bind.md b/components/autocomplete/data-bind.md index 75b85c3d0c..f380ecd47d 100644 --- a/components/autocomplete/data-bind.md +++ b/components/autocomplete/data-bind.md @@ -92,57 +92,7 @@ To bind the AutoComplete to a model: } ```` -## Considerations - -### Reference - -The AutoComplete is a generic component and its type depends on the type of its `Data` and `Value`. - -
-````RAZOR String -@*Reference when binding to a string collection*@ - - - -@code{ - private TelerikAutoComplete AutoCompleteRef { get; set; } - - private string AutoCompleteValue { get; set; } - - private List Suggestions { get; set; } = new List { "first", "second", "third" }; -} -```` -````RAZOR Model -@*Reference when binding to a model collection*@ - - - -@code{ - private TelerikAutoComplete AutoCompleteRef { get; set; } - - private string AutoCompleteValue { get; set; } - - private List Suggestions { get; set; } = new List - { - new SuggestionsModel { Suggestion = "first", SomeOtherField = 1 }, - new SuggestionsModel { Suggestion = "second", SomeOtherField = 2 }, - new SuggestionsModel { Suggestion = "third", SomeOtherField = 3 } - }; - - public class SuggestionsModel - { - public string Suggestion { get; set; }//the auto complete needs only the string field - public int SomeOtherField { get; set; } - } -} -```` - -### Missing Data +## Missing Data 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. diff --git a/components/autocomplete/overview.md b/components/autocomplete/overview.md index acbe6b685e..92d6411f52 100644 --- a/components/autocomplete/overview.md +++ b/components/autocomplete/overview.md @@ -145,9 +145,7 @@ The AutoComplete provides the following popup settings: ## AutoComplete Reference and Methods -The AutoComplete is a generic component and its type is determined by the type of the model you use as its data source. You can find examples in the [Data Bind - Considerations](slug:autocomplete-databind#considerations) article. - -Add a reference to the component instance to use the [AutoComplete's methods](slug:Telerik.Blazor.Components.TelerikAutoComplete-1). +Add a reference to the component instance to use the [AutoComplete's methods](slug:Telerik.Blazor.Components.TelerikAutoComplete-1). Note that the [AutoComplete is a generic component](slug:common-features-data-binding-overview#component-type). @[template](/_contentTemplates/dropdowns/methods.md#methods-list) diff --git a/components/combobox/data-bind.md b/components/combobox/data-bind.md index f8e07d49fe..c2674e466d 100644 --- a/components/combobox/data-bind.md +++ b/components/combobox/data-bind.md @@ -23,7 +23,6 @@ There are also some considerations you may find useful, such as showing the `Pla * [Considerations](#considerations) * [Value Out of Range](#value-out-of-range) - * [Component Reference](#component-reference) * [Missing Value or Data](#missing-value-or-data) ## Strings and Value Types @@ -105,7 +104,7 @@ To bind the ComboBox to a model: ## Considerations -The ComboBox 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 app, because the component will not change it. +The ComboBox 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](slug:common-features-data-binding-overview#component-type) 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 app, because the component will not change it. ### Value Out of Range @@ -119,63 +118,6 @@ Handling such "unexpected" values is up to the application - for example, throug When `AllowCustom="true"`, what the user types in the input will be set to the `Value` of the component regardless of the data source. -### Component Reference - -The ComboBox is a generic component and its type depends on the type of its `Data` and `Value`. - -
-````RAZOR String -@*ComboBox reference when binding to a string collection*@ - - - - -@code { - private TelerikComboBox? ComboBoxRef { get; set; } - - private List ComboBoxData = new List() { "first", "second", "third" }; - - private string ComboBoxValue { get; set; } = string.Empty; - - protected override void OnInitialized() - { - ComboBoxValue = "third"; - } -} -```` -````RAZOR Model -@*ComboBox reference when binding to a model collection*@ - - - - -@code { - private TelerikComboBox? ComboBoxRef { get; set; } - - private IEnumerable ComboBoxData = Enumerable.Range(1, 20) - .Select(x => new ComboBoxItem { MyTextField = "Item " + x, MyValueField = x }); - - private int ComboBoxValue { get; set; } - - protected override void OnInitialized() - { - ComboBoxValue = 3; - } - - public class ComboBoxItem - { - public int MyValueField { get; set; } - public string MyTextField { get; set; } = string.Empty; - } -} -```` - ### Missing Value or Data In case you cannot provide strongly-typed `Value` or `Data` at compile time, you need to set the corresponding type properties to the `TItem` and `TValue` properties as shown below. diff --git a/components/combobox/overview.md b/components/combobox/overview.md index 4dfa3234ab..da21130657 100644 --- a/components/combobox/overview.md +++ b/components/combobox/overview.md @@ -145,9 +145,8 @@ The ComboBox provides the following popup settings: ## ComboBox Reference and Methods -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. +Add a reference to the component instance to use the [ComboBox's methods](slug:Telerik.Blazor.Components.TelerikComboBox-2). Note that the [ComboBox is a generic component](slug:common-features-data-binding-overview#component-type). -Add a reference to the component instance to use the [ComboBox's methods](slug:Telerik.Blazor.Components.TelerikComboBox-2). @[template](/_contentTemplates/dropdowns/methods.md#methods-list) diff --git a/components/dropdownlist/data-bind.md b/components/dropdownlist/data-bind.md index f3a2d27f98..48d89fd724 100644 --- a/components/dropdownlist/data-bind.md +++ b/components/dropdownlist/data-bind.md @@ -23,7 +23,6 @@ There are also some considerations you may find useful, such as showing the `Def * [Considerations](#considerations) * [Value Out of Range](#value-out-of-range) - * [Component Reference](#component-reference) * [Missing Value or Data](#missing-value-or-data) ## Strings or Value Types @@ -93,7 +92,7 @@ To bind the DropDownList to a model: ## Considerations -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). Providing a [value that is not in the data source](#value-out-of-range) needs to be taken into account be the app, because the component will not change it. +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](slug:common-features-data-binding-overview#component-type) 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 app, because the component will not change it. ### Value Out of Range @@ -102,57 +101,6 @@ When the `Value` the application provides does not match any of the values prese If you have set the `DefaultText` 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 `DefaultText`. A `Value` that is non-`default` will not show the `DefaultText`. 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`. - -### Component Reference - -The DropDownList is a generic component and its type depends on the type of its `Data` and `Value`. - -
-````RAZOR String - - -@code { - private TelerikDropDownList? DropDownListRef { get; set; } - - private List DropDownListData = new List() { "first", "second", "third" }; - - private string DropDownListValue { get; set; } = string.Empty; - - protected override void OnInitialized() - { - DropDownListValue = "second"; - } -} -```` -````RAZOR Model - - -@code { - private TelerikDropDownList? DropDownListRef { get; set; } - - private int DropDownListValue { get; set; } - - private IEnumerable DropDownListData = Enumerable.Range(1, 20) - .Select(x => new DropDownListItem { Text = $"Item {x}", Value = x }); - - protected override void OnInitialized() - { - DropDownListValue = 3; - } - - public class DropDownListItem - { - public int Value { get; set; } - public string Text { get; set; } = string.Empty; - } -} -```` ### Missing Value or Data diff --git a/components/dropdownlist/overview.md b/components/dropdownlist/overview.md index 561965a5aa..e40d20d5d8 100644 --- a/components/dropdownlist/overview.md +++ b/components/dropdownlist/overview.md @@ -145,9 +145,8 @@ The DropDownList provides the following popup settings: ## DropDownList Reference and Methods -The DropDownList is a generic component and its type comes from the model it is bound to and from the value field type. See the [Component Reference](slug:components/dropdownlist/databind#component-reference) section in the Data Binding article for details and examples. +Add a reference to the component instance to use the [DropDownList's methods](slug:Telerik.Blazor.Components.TelerikDropDownList-2). Note that the [DropDownList is a generic component](slug:common-features-data-binding-overview#component-type). -Add a reference to the component instance to use the [DropDownList's methods](slug:Telerik.Blazor.Components.TelerikDropDownList-2). @[template](/_contentTemplates/dropdowns/methods.md#methods-list) diff --git a/components/multicolumncombobox/data-bind.md b/components/multicolumncombobox/data-bind.md index fa4826e313..2ccbc89eb6 100644 --- a/components/multicolumncombobox/data-bind.md +++ b/components/multicolumncombobox/data-bind.md @@ -53,7 +53,7 @@ Missing selection is most common when: ## Missing Value or Data -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). +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:common-features-data-binding-overview#component-type). 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). diff --git a/components/multicolumncombobox/overview.md b/components/multicolumncombobox/overview.md index 313e883c97..ea6b2b9cd8 100644 --- a/components/multicolumncombobox/overview.md +++ b/components/multicolumncombobox/overview.md @@ -166,11 +166,7 @@ The MultiColumnComboBox provides the following popup settings: ## Component Reference and Methods -To execute MultiColumnComboBox methods, obtain reference to the component instance via `@ref`. - -The MultiColumnComboBox is a generic component. Its type depends on the type of its model and the type of its `Value`. 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). - -The table below lists the MultiComboBox methods. Also consult the [MultiColumnComboBox API](slug:Telerik.Blazor.Components.TelerikMultiColumnComboBox-2). +Add a reference to the component instance to use the [MultiColumnComboBox's methods](slug:Telerik.Blazor.Components.TelerikMultiColumnComboBox-2). Note that the [MultiColumnComboBox is a generic component](slug:common-features-data-binding-overview#component-type). | Method | Description | | --- | --- | diff --git a/components/multiselect/data-bind.md b/components/multiselect/data-bind.md index 6000ec15c2..d21e142013 100644 --- a/components/multiselect/data-bind.md +++ b/components/multiselect/data-bind.md @@ -128,57 +128,7 @@ To bind the MultiSelect to a model: ## Considerations -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). - -### Reference - -The MultiSelect is a generic component and its type depends on the type of its `Data` and `Value`. - -
-````RAZOR String -@*Reference type when binding to a string collection*@ - - - -@code { - private TelerikMultiSelect? MultiSelectRef { get; set; } - - private List MultiSelectValue { get; set; } = new(); - - private List MultiSelectData { get; set; } = new List { "first", "second", "third" }; -} -```` -````RAZOR Model -@*Reference when binding to a model collection*@ - - - -@code { - private TelerikMultiSelect? MultiSelectRef { get; set; } - - private List MultiSelectValue { get; set; } = new(); - - private List MultiSelectData { get; set; } = new List() - { - new MultiSelectItem { Text = "first", Value = 1 }, - new MultiSelectItem { Text = "second", Value = 2 }, - new MultiSelectItem { Text = "third", Value = 3 } - }; - - public class MultiSelectItem - { - public string Text { get; set; } = string.Empty; - - public int Value { get; set; } - } -} -```` +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](slug:common-features-data-binding-overview#component-type) and what happens [if you can't provide data or a value](#missing-value-or-data). ### Missing Value Or Data diff --git a/components/multiselect/overview.md b/components/multiselect/overview.md index f95842f7f3..29c438c9ee 100644 --- a/components/multiselect/overview.md +++ b/components/multiselect/overview.md @@ -165,9 +165,8 @@ The MultiSelect provides the following popup settings: ## MultiSelect Reference and Methods -The MultiSelect is a generic component and its type is determined by the type of the model you use as its data source. You can find examples in the [Data Bind - Considerations](slug:multiselect-databind#considerations) article. +Add a reference to the component instance to use the [MultiSelect's methods](slug:Telerik.Blazor.Components.TelerikMultiSelect-2). Note that the [MultiSelect is a generic component](slug:common-features-data-binding-overview#component-type). -Add a reference to the component instance to use the [MultiSelect's methods](slug:Telerik.Blazor.Components.TelerikMultiSelect-2). @[template](/_contentTemplates/dropdowns/methods.md#methods-list)