Skip to content

Commit 502047f

Browse files
ntachevantacheva
authored
[3.7] docs(selects):Adaptive rendering docs (#1134)
* docs(selects):Adaptive rendering docs * docs(selects): adress feedback * docs(selects, pickers): add events note in all compoennts * docs(pickers, selects): add adaptive rendering intro in overview articles * chore(dropdownlist, adaptive rendering): fix duplicated section and order * docs(selects,pickers): add AdaptiveMode and Title to parameters table * chore(selects,pickers):fixes * chore(pickers, selects): cleanup and fixes
1 parent fa6ece4 commit 502047f

File tree

19 files changed

+361
-217
lines changed

19 files changed

+361
-217
lines changed

‎_contentTemplates/dropdowns/adaptive-rendering.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#intro
2+
The component supports different popup rendering depending on the screen size. [Read more about the Adaptive Rendering functionality and how to enable it...]({%slug adaptive-rendering%})
3+
#end
4+
5+
#value-changed
6+
> If [`AdaptiveRendering`]({%slug adaptive-rendering%}) is enabled, on small and medium devices `ValueChanged` will fire only when the user clicks the confirmation button in the action sheet.
7+
#end

‎common-features/adaptive-rendering.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Adaptive Rendering
3+
page_title: Adaptive Rendering
4+
description: Explore how the components with popup elements can react to the changes in the
5+
slug: adaptive-rendering
6+
tags: telerik,blazor,adaptive,rendering,mobile
7+
published: True
8+
position: 0
9+
---
10+
11+
# Adaptive Rendering
12+
13+
Telerik UI for Blazor supports adaptive rendering for the components that incorporate popup elements. This functionality allows the component to adapt to the screen size by providing different rendering of the popup element based on the screen dimensions.
14+
15+
>caption In this article:
16+
17+
* [Supported components](#supported-components)
18+
* [Basics](#basics)
19+
* [Rendering specifics](#rendering-specifics)
20+
* [Limitations](#limitations)
21+
22+
## Supported components
23+
24+
The adaptive rendering functionality is supported by the following components:
25+
26+
* [AutoComplete]({%slug autocomplete-overview%})
27+
* [ComboBox]({%slug components/combobox/overview%})
28+
* [DatePicker]({%slug components/datepicker/overview%})
29+
* [DateRangePicker]({%slug daterangepicker-overview%})
30+
* [DateTimePicker]({%slug components/datetimepicker/overview%})
31+
* [DropDownList]({%slug components/dropdownlist/overview%})
32+
* [MultiColumnComboBox]({%slug multicolumncombobox-overview%})
33+
* [MultiSelect]({%slug multiselect-overview%})
34+
* [TimePicker]({%slug components/timepicker/overview%})
35+
36+
## Basics
37+
38+
To enable the adaptive rendering use the `AdaptiveMode` parameter. It takes a member of the `AdaptiveMode` enum:
39+
40+
* `None` (default)
41+
* `Auto`
42+
43+
Optionally, you may set the `Title` parameter to provide custom header text for the popup on small and medium devices.
44+
45+
>caption Enable the adaptive rendering
46+
47+
````CSHTML
48+
// NOTE: The configurations below includes only the DropDownList, but it is applicable to all of the above listed components
49+
50+
// Adapts to the screen size to use the appropriate rendering.
51+
<TelerikDropDownList ... AdaptiveMode="@AdaptiveMode.Auto" Title="Select item"... />
52+
````
53+
54+
# Rendering specifics
55+
56+
When you set the `AdaptiveMode` to `Auto`, the component will take the screen size into consideration to use the appropriate rendering. The different rendering targets the popup element of the component and how it will be displayed to the user.
57+
58+
Three breakpoints define the rendering options as follows:
59+
60+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
61+
62+
|| **Small** | **Medium** | **Large** |
63+
|-------|-------|--------|-------|
64+
**Dimensions** | up to 500px | 501px to 768px | over 768px |
65+
**Rendering** | The popup is rendered as a fullscreen action sheet. | The popup is rendered as an action sheet docked to the bottom of the screen. | The popup is rendered as an animation container docked to the main element of the component. |
66+
67+
## Limitations
68+
69+
* Custom values - some of the listed components allow custom values (for example, [ComboBox]({%slug components/combobox/custom-value%}), [MultiColumnComboBox]({%slug multicolumncombobox-custom-value%})). This feature is not compatible with `AdaptiveMode.Auto`.
70+
71+
## See also
72+
73+
* [Live Demo: AutoComplete](https://demos.telerik.com/blazor-ui/autocomplete/adaptive)
74+
* [Live Demo: ComboBox](https://demos.telerik.com/blazor-ui/combobox/adaptive)
75+
* [Live Demo: DatePicker](https://demos.telerik.com/blazor-ui/datepicker/adaptive)
76+
* [Live Demo: DateRangePicker](https://demos.telerik.com/blazor-ui/daterangepicker/adaptive)
77+
* [Live Demo: DateTimePicker](https://demos.telerik.com/blazor-ui/datetimepicker/adaptive)
78+
* [Live Demo: DropDownList](https://demos.telerik.com/blazor-ui/dropdownlist/adaptive)
79+
* [Live Demo: MultiColumnComboBox](https://demos.telerik.com/blazor-ui/multicolumncombobox/adaptive)
80+
* [Live Demo: MultiSelect](https://demos.telerik.com/blazor-ui/multiselect/adaptive)
81+
* [Live Demo: TimePicker](https://demos.telerik.com/blazor-ui/timepicker/adaptive)

‎components/autocomplete/overview.md‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,10 @@ The Blazor AutoComplete @[template](/_contentTemplates/dropdowns/features.md#gro
6868

6969
@[template](/_contentTemplates/dropdowns/features.md#virtualization) [Read more about the Blazor AutoComplete virtualization...]({% slug autocomplete-virtualization %})
7070

71+
## Adaptive Rendering
72+
73+
@[template](/_contentTemplates/dropdowns/adaptive-rendering.md#intro)
74+
7175
## Parameters
7276

7377
The Blazor AutoComplete provides various parameters that allow you to configure the component:
@@ -76,20 +80,22 @@ The Blazor AutoComplete provides various parameters that allow you to configure
7680

7781
| Parameter | Type | Description |
7882
| ----------- | ----------- | -------|
79-
| `Data` | `IEnumerable<TItem>` | allows you to provide the data source. Required.
80-
| `DebounceDelay` | `int` <br/> 150 | Time in milliseconds between the last typed symbol and the internal `oninput` event firing. Applies when the user types and filters. Use it to balance between client-side performance and number of database queries.
83+
| `AdaptiveMode` | `AdaptiveMode` <br /> (`None`) | The [adaptive mode]({%slug adaptive-rendering%}) of the component. |
84+
| `Data` | `IEnumerable<TItem>` | allows you to provide the data source. Required. |
85+
| `DebounceDelay` | `int` <br/> 150 | Time in milliseconds between the last typed symbol and the internal `oninput` event firing. Applies when the user types and filters. Use it to balance between client-side performance and number of database queries. |
8186
| `Enabled` | `bool` | Whether the component is enabled. |
8287
| `Filterable` | `bool` | Whether [filtering]({%slug multiselect-filter%}) is enabled for the end user (suggestions will get narrowed down as they type). |
8388
| `FilterOperator` | `StringFilterOperator` <br /> (`StartsWith`) | The string operation that will be used for [filtering]({%slug multiselect-filter%}). |
8489
| `Id` | `string` | Renders as the `id` attribute on the `<input />` element, so you can attach a `<label for="">` to the input.|
85-
| `TItem` | `Type` | 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.|
90+
| `TItem` | `Type` | 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. |
91+
| `Title` | `string` | The title text rendered in the header of the popup(action sheet). Applicable only when [`AdaptiveMode` is set to `Auto`]({%slug adaptive-rendering%}). |
8692
| `Value` and `bind-Value` | `string` | Get/set the value of the component, can be used for binding. Use the `@bind-Value` syntax for two-way binding, for example, to a variable of your own. The `Value` must be a `string`.|
87-
| `ValueField` | `string` <br /> (`Value`) | The name of the field from the model that will be shown as hints to the user. Not required when binding to a simple list of strings.|
88-
| `TabIndex` | `int?` | Maps to the `tabindex` attribute of the HTML element. You can use it to customize the order in which the inputs in your form focus with the `Tab` key.|
89-
| `ClearButton` | `bool` | Whether the user will have the option to clear the selected value with a button on the input. When it is clicked, the `Value` will be updated to `string.Empty`.|
90-
| `Enabled` | `bool` | Use this Boolean property to render a disabled Blazor AutoComplete component until certain requirements are met.|
91-
| `MinLength` | `int` | How many characters the text has to be before the suggestions list appears. Cannot be `0`. Often works together with [filtering]({%slug autocomplete-filter%}).|
92-
| `Placeholder` | `string` | The text the user sees as a hint when there is no text in the input. In order for it to be shown, the `Value` parameter should be set to the default value for string (`null`).|
93+
| `ValueField` | `string` <br /> (`Value`) | The name of the field from the model that will be shown as hints to the user. Not required when binding to a simple list of strings. |
94+
| `TabIndex` | `int?` | Maps to the `tabindex` attribute of the HTML element. You can use it to customize the order in which the inputs in your form focus with the `Tab` key. |
95+
| `ClearButton` | `bool` | Whether the user will have the option to clear the selected value with a button on the input. When it is clicked, the `Value` will be updated to `string.Empty`. |
96+
| `Enabled` | `bool` | Use this Boolean property to render a disabled Blazor AutoComplete component until certain requirements are met. |
97+
| `MinLength` | `int` | How many characters the text has to be before the suggestions list appears. Cannot be `0`. Often works together with [filtering]({%slug autocomplete-filter%}). |
98+
| `Placeholder` | `string` | The text the user sees as a hint when there is no text in the input. In order for it to be shown, the `Value` parameter should be set to the default value for string (`null`). |
9399

94100
### Styling and Appearance
95101

‎components/combobox/custom-value.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,9 @@ Selected value: @selectedValue
101101
}
102102
````
103103

104+
## Limitations
104105

106+
* `AllowCustom` is not compatible with [Adaptive rendering]({%slug adaptive-rendering%}).
105107

106108
## See Also
107109

‎components/combobox/overview.md‎

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,9 @@ The Blazor ComboBox @[template](/_contentTemplates/dropdowns/features.md#groupin
6969

7070
@[template](/_contentTemplates/dropdowns/features.md#virtualization) [Read more about the Blazor ComboBox virtualization...]({% slug combobox-virtualization %})
7171

72+
## Adaptive Rendering
73+
74+
@[template](/_contentTemplates/dropdowns/adaptive-rendering.md#intro)
7275

7376
## Parameters
7477

@@ -78,21 +81,23 @@ The Blazor ComboBox @[template](/_contentTemplates/dropdowns/features.md#groupin
7881

7982
| Parameter | Type | Description
8083
| ----------- | ----------- | -----------|
81-
| `AllowCustom` | `bool` | whether the user can enter [custom values]({%slug components/combobox/custom-value%}). If enabled, the `ValueField` must be a `string`.
82-
| `ClearButton` | `bool` | 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`.
83-
| `Data` | `IEnumerable<TItem>` | allows you to provide the data source. Required.
84-
| `DebounceDelay` | `int` <br/> 150 | Time in milliseconds between the last typed symbol and the internal `oninput` event firing. Applies when the user types and filters. Use it to balance between client-side performance and number of database queries.
85-
| `Enabled` | `bool` | whether the component is enabled.
86-
|`Filterable` | `bool` | whether [filtering]({%slug components/combobox/filter%}) is enabled for the end user.
87-
| `FilterOperator` | `StringFilterOperator` <br /> (`StartsWith`) | the method of [filtering]({%slug components/combobox/filter%}) the items.
88-
| `Id` | `string` | renders as the `id` attribute on the `<input />` element, so you can attach a `<label for="">` to the input.
89-
| `Placeholder` | `string` | the text the user sees as a hint when no item is selected. In order for it to be shown, the `Value` parameter should be set to a default value depending on the type defined in the `ValueField` parameter. For example, `0` for an `int`, and `null` for an `int?` or `string`. You need to make sure that it does not match the value of an existing item in the data source.
90-
| `TItem` | `Type` | 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.
91-
| `TValue` | `Type` | 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. The type of the values can be:<br /> - `number` (such as `int`, `double`, and so on)<br /> - `string`<br /> - `Guid`<br /> - `Enum`|
92-
| `TextField` | `string` <br /> (`Text`)| the name of the field from the model that will be shown to the user.
93-
| `ValueField` | `string` <br /> (`Value`) | the name of the field from the model that will be the underlying `value`.
94-
| `Value` and `bind-Value` | `TValue` | 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.
95-
| `TabIndex` | `int?` | maps to the `tabindex` attribute of the HTML element. You can use it to customize the order in which the inputs in your form focus with the `Tab` key.
84+
| `AdaptiveMode` | `AdaptiveMode` <br /> (`None`) | The [adaptive mode]({%slug adaptive-rendering%}) of the component. |
85+
| `AllowCustom` | `bool` | whether the user can enter [custom values]({%slug components/combobox/custom-value%}). If enabled, the `ValueField` must be a `string`. |
86+
| `ClearButton` | `bool` | 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`. |
87+
| `Data` | `IEnumerable<TItem>` | allows you to provide the data source. Required. |
88+
| `DebounceDelay` | `int` <br/> 150 | Time in milliseconds between the last typed symbol and the internal `oninput` event firing. Applies when the user types and filters. Use it to balance between client-side performance and number of database queries. |
89+
| `Enabled` | `bool` | whether the component is enabled. |
90+
|`Filterable` | `bool` | whether [filtering]({%slug components/combobox/filter%}) is enabled for the end user. |
91+
| `FilterOperator` | `StringFilterOperator` <br /> (`StartsWith`) | the method of [filtering]({%slug components/combobox/filter%}) the items. |
92+
| `Id` | `string` | renders as the `id` attribute on the `<input />` element, so you can attach a `<label for="">` to the input. |
93+
| `Placeholder` | `string` | the text the user sees as a hint when no item is selected. In order for it to be shown, the `Value` parameter should be set to a default value depending on the type defined in the `ValueField` parameter. For example, `0` for an `int`, and `null` for an `int?` or `string`. You need to make sure that it does not match the value of an existing item in the data source. |
94+
| `TItem` | `Type` | 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. |
95+
| `TValue` | `Type` | 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. The type of the values can be:<br /> - `number` (such as `int`, `double`, and so on)<br /> - `string`<br /> - `Guid`<br /> - `Enum` |
96+
| `Title` | `string` | The title text rendered in the header of the popup(action sheet). Applicable only when [`AdaptiveMode` is set to `Auto`]({%slug adaptive-rendering%}). |
97+
| `TextField` | `string` <br /> (`Text`)| the name of the field from the model that will be shown to the user. |
98+
| `ValueField` | `string` <br /> (`Value`) | the name of the field from the model that will be the underlying `value`. |
99+
| `Value` and `bind-Value` | `TValue` | 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. |
100+
| `TabIndex` | `int?` | maps to the `tabindex` attribute of the HTML element. You can use it to customize the order in which the inputs in your form focus with the `Tab` key. |
96101

97102
### Styling and Appearance
98103

0 commit comments

Comments
 (0)