Skip to content

Commit 252f073

Browse files
authored
chore(selects): Optimize reference documentation (#2981)
* chore(selects): Optimize reference documentation * Update components/combobox/data-bind.md * Update components/dropdownlist/data-bind.md
1 parent b1453d8 commit 252f073

File tree

10 files changed

+10
-229
lines changed

10 files changed

+10
-229
lines changed

components/autocomplete/data-bind.md

Lines changed: 1 addition & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -92,57 +92,7 @@ To bind the AutoComplete to a model:
9292
}
9393
````
9494

95-
## Considerations
96-
97-
### Reference
98-
99-
The AutoComplete is a generic component and its type depends on the type of its `Data` and `Value`.
100-
101-
<div class="skip-repl"></div>
102-
````RAZOR String
103-
@*Reference when binding to a string collection*@
104-
105-
<TelerikAutoComplete @ref="@AutoCompleteRef"
106-
Data="@Suggestions"
107-
@bind-Value="@AutoCompleteValue" />
108-
109-
@code{
110-
private TelerikAutoComplete<string> AutoCompleteRef { get; set; }
111-
112-
private string AutoCompleteValue { get; set; }
113-
114-
private List<string> Suggestions { get; set; } = new List<string> { "first", "second", "third" };
115-
}
116-
````
117-
````RAZOR Model
118-
@*Reference when binding to a model collection*@
119-
120-
<TelerikAutoComplete @ref="@AutoCompleteRef"
121-
Data="@Suggestions"
122-
@bind-Value="@AutoCompleteValue"
123-
ValueField="@( nameof(SuggestionsModel.Suggestion) )" />
124-
125-
@code{
126-
private TelerikAutoComplete<SuggestionsModel> AutoCompleteRef { get; set; }
127-
128-
private string AutoCompleteValue { get; set; }
129-
130-
private List<SuggestionsModel> Suggestions { get; set; } = new List<SuggestionsModel>
131-
{
132-
new SuggestionsModel { Suggestion = "first", SomeOtherField = 1 },
133-
new SuggestionsModel { Suggestion = "second", SomeOtherField = 2 },
134-
new SuggestionsModel { Suggestion = "third", SomeOtherField = 3 }
135-
};
136-
137-
public class SuggestionsModel
138-
{
139-
public string Suggestion { get; set; }//the auto complete needs only the string field
140-
public int SomeOtherField { get; set; }
141-
}
142-
}
143-
````
144-
145-
### Missing Data
95+
## Missing Data
14696

14797
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.
14898

components/autocomplete/overview.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -145,9 +145,7 @@ The AutoComplete provides the following popup settings:
145145

146146
## AutoComplete Reference and Methods
147147

148-
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.
149-
150-
Add a reference to the component instance to use the [AutoComplete's methods](slug:Telerik.Blazor.Components.TelerikAutoComplete-1).
148+
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).
151149

152150
@[template](/_contentTemplates/dropdowns/methods.md#methods-list)
153151

components/combobox/data-bind.md

Lines changed: 1 addition & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@ There are also some considerations you may find useful, such as showing the `Pla
2323

2424
* [Considerations](#considerations)
2525
* [Value Out of Range](#value-out-of-range)
26-
* [Component Reference](#component-reference)
2726
* [Missing Value or Data](#missing-value-or-data)
2827

2928
## Strings and Value Types
@@ -105,7 +104,7 @@ To bind the ComboBox to a model:
105104

106105
## Considerations
107106

108-
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.
107+
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 by the app, because the component will not change it.
109108

110109
### Value Out of Range
111110

@@ -119,63 +118,6 @@ Handling such "unexpected" values is up to the application - for example, throug
119118

120119
When `AllowCustom="true"`, what the user types in the input will be set to the `Value` of the component regardless of the data source.
121120

122-
### Component Reference
123-
124-
The ComboBox is a generic component and its type depends on the type of its `Data` and `Value`.
125-
126-
<div class="skip-repl"></div>
127-
````RAZOR String
128-
@*ComboBox reference when binding to a string collection*@
129-
130-
<TelerikComboBox @ref="ComboBoxRef"
131-
Data="@ComboBoxData"
132-
Value="@ComboBoxValue">
133-
</TelerikComboBox>
134-
135-
@code {
136-
private TelerikComboBox<string, string>? ComboBoxRef { get; set; }
137-
138-
private List<string> ComboBoxData = new List<string>() { "first", "second", "third" };
139-
140-
private string ComboBoxValue { get; set; } = string.Empty;
141-
142-
protected override void OnInitialized()
143-
{
144-
ComboBoxValue = "third";
145-
}
146-
}
147-
````
148-
````RAZOR Model
149-
@*ComboBox reference when binding to a model collection*@
150-
151-
<TelerikComboBox @ref="@ComboBoxRef"
152-
Data="@ComboBoxData"
153-
@bind-Value="@ComboBoxValue"
154-
TextField="@nameof(ComboBoxItem.MyTextField)"
155-
ValueField="@nameof(ComboBoxItem.MyValueField)">
156-
</TelerikComboBox>
157-
158-
@code {
159-
private TelerikComboBox<ComboBoxItem, int>? ComboBoxRef { get; set; }
160-
161-
private IEnumerable<ComboBoxItem> ComboBoxData = Enumerable.Range(1, 20)
162-
.Select(x => new ComboBoxItem { MyTextField = "Item " + x, MyValueField = x });
163-
164-
private int ComboBoxValue { get; set; }
165-
166-
protected override void OnInitialized()
167-
{
168-
ComboBoxValue = 3;
169-
}
170-
171-
public class ComboBoxItem
172-
{
173-
public int MyValueField { get; set; }
174-
public string MyTextField { get; set; } = string.Empty;
175-
}
176-
}
177-
````
178-
179121
### Missing Value or Data
180122

181123
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.

components/combobox/overview.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -145,9 +145,8 @@ The ComboBox provides the following popup settings:
145145

146146
## ComboBox Reference and Methods
147147

148-
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.
148+
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).
149149

150-
Add a reference to the component instance to use the [ComboBox's methods](slug:Telerik.Blazor.Components.TelerikComboBox-2).
151150

152151
@[template](/_contentTemplates/dropdowns/methods.md#methods-list)
153152

components/dropdownlist/data-bind.md

Lines changed: 1 addition & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@ There are also some considerations you may find useful, such as showing the `Def
2323

2424
* [Considerations](#considerations)
2525
* [Value Out of Range](#value-out-of-range)
26-
* [Component Reference](#component-reference)
2726
* [Missing Value or Data](#missing-value-or-data)
2827

2928
## Strings or Value Types
@@ -93,7 +92,7 @@ To bind the DropDownList to a model:
9392

9493
## Considerations
9594

96-
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.
95+
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 by the app, because the component will not change it.
9796

9897
### Value Out of Range
9998

@@ -102,57 +101,6 @@ When the `Value` the application provides does not match any of the values prese
102101
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`.
103102

104103
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`.
105-
106-
### Component Reference
107-
108-
The DropDownList is a generic component and its type depends on the type of its `Data` and `Value`.
109-
110-
<div class="skip-repl"></div>
111-
````RAZOR String
112-
<TelerikDropDownList @ref="@DropDownListRef"
113-
Data="@DropDownListData"
114-
@bind-Value="DropDownListValue" />
115-
116-
@code {
117-
private TelerikDropDownList<string, string>? DropDownListRef { get; set; }
118-
119-
private List<string> DropDownListData = new List<string>() { "first", "second", "third" };
120-
121-
private string DropDownListValue { get; set; } = string.Empty;
122-
123-
protected override void OnInitialized()
124-
{
125-
DropDownListValue = "second";
126-
}
127-
}
128-
````
129-
````RAZOR Model
130-
<TelerikDropDownList @ref="@DropDownListRef"
131-
Data="@DropDownListData"
132-
@bind-Value="DropDownListValue"
133-
TextField="@nameof(DropDownListItem.Text)"
134-
ValueField="@nameof(DropDownListItem.Value)" />
135-
136-
@code {
137-
private TelerikDropDownList<DropDownListItem, int>? DropDownListRef { get; set; }
138-
139-
private int DropDownListValue { get; set; }
140-
141-
private IEnumerable<DropDownListItem> DropDownListData = Enumerable.Range(1, 20)
142-
.Select(x => new DropDownListItem { Text = $"Item {x}", Value = x });
143-
144-
protected override void OnInitialized()
145-
{
146-
DropDownListValue = 3;
147-
}
148-
149-
public class DropDownListItem
150-
{
151-
public int Value { get; set; }
152-
public string Text { get; set; } = string.Empty;
153-
}
154-
}
155-
````
156104

157105
### Missing Value or Data
158106

components/dropdownlist/overview.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -145,9 +145,8 @@ The DropDownList provides the following popup settings:
145145

146146
## DropDownList Reference and Methods
147147

148-
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.
148+
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).
149149

150-
Add a reference to the component instance to use the [DropDownList's methods](slug:Telerik.Blazor.Components.TelerikDropDownList-2).
151150

152151
@[template](/_contentTemplates/dropdowns/methods.md#methods-list)
153152

components/multicolumncombobox/data-bind.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ Missing selection is most common when:
5353

5454
## Missing Value or Data
5555

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).
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:common-features-data-binding-overview#component-type).
5757

5858
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).
5959

components/multicolumncombobox/overview.md

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -166,11 +166,7 @@ The MultiColumnComboBox provides the following popup settings:
166166

167167
## Component Reference and Methods
168168

169-
To execute MultiColumnComboBox methods, obtain reference to the component instance via `@ref`.
170-
171-
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).
172-
173-
The table below lists the MultiComboBox methods. Also consult the [MultiColumnComboBox API](slug:Telerik.Blazor.Components.TelerikMultiColumnComboBox-2).
169+
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).
174170

175171
| Method | Description |
176172
| --- | --- |

components/multiselect/data-bind.md

Lines changed: 1 addition & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -128,57 +128,7 @@ To bind the MultiSelect to a model:
128128

129129
## Considerations
130130

131-
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).
132-
133-
### Reference
134-
135-
The MultiSelect is a generic component and its type depends on the type of its `Data` and `Value`.
136-
137-
<div class="skip-repl"></div>
138-
````RAZOR String
139-
@*Reference type when binding to a string collection*@
140-
141-
<TelerikMultiSelect @ref="@MultiSelectRef"
142-
Data="@MultiSelectData"
143-
@bind-Value="@MultiSelectValue" />
144-
145-
@code {
146-
private TelerikMultiSelect<string, string>? MultiSelectRef { get; set; }
147-
148-
private List<string> MultiSelectValue { get; set; } = new();
149-
150-
private List<string> MultiSelectData { get; set; } = new List<string> { "first", "second", "third" };
151-
}
152-
````
153-
````RAZOR Model
154-
@*Reference when binding to a model collection*@
155-
156-
<TelerikMultiSelect @ref="@MultiSelectRef"
157-
Data="@MultiSelectData"
158-
@bind-Value="@MultiSelectValue"
159-
TextField="@nameof(MultiSelectItem.Text)"
160-
ValueField="@nameof(MultiSelectItem.Value)" />
161-
162-
@code {
163-
private TelerikMultiSelect<MultiSelectItem, int>? MultiSelectRef { get; set; }
164-
165-
private List<int> MultiSelectValue { get; set; } = new();
166-
167-
private List<MultiSelectItem> MultiSelectData { get; set; } = new List<MultiSelectItem>()
168-
{
169-
new MultiSelectItem { Text = "first", Value = 1 },
170-
new MultiSelectItem { Text = "second", Value = 2 },
171-
new MultiSelectItem { Text = "third", Value = 3 }
172-
};
173-
174-
public class MultiSelectItem
175-
{
176-
public string Text { get; set; } = string.Empty;
177-
178-
public int Value { get; set; }
179-
}
180-
}
181-
````
131+
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).
182132

183133
### Missing Value Or Data
184134

components/multiselect/overview.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -165,9 +165,8 @@ The MultiSelect provides the following popup settings:
165165

166166
## MultiSelect Reference and Methods
167167

168-
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.
168+
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).
169169

170-
Add a reference to the component instance to use the [MultiSelect's methods](slug:Telerik.Blazor.Components.TelerikMultiSelect-2).
171170

172171
@[template](/_contentTemplates/dropdowns/methods.md#methods-list)
173172

0 commit comments

Comments
 (0)