[3.7] docs(selects):Adaptive rendering docs

_contentTemplates/dropdowns/adaptive-rendering.md

@@ -0,0 +1,7 @@
+#intro
+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%})
+#end
+
+#value-changed
+> 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.
+#end

common-features/adaptive-rendering.md

@@ -0,0 +1,81 @@
+---
+title: Adaptive Rendering
+page_title: Adaptive Rendering
+description: Explore how the components with popup elements can react to the changes in the
+slug: adaptive-rendering
+tags: telerik,blazor,adaptive,rendering,mobile
+published: True
+position: 0
+---
+
+# Adaptive Rendering
+
+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.
+
+>caption In this article:
+
+* [Supported components](#supported-components)
+* [Basics](#basics)
+* [Rendering specifics](#rendering-specifics)
+* [Limitations](#limitations)
+
+## Supported components
+
+The adaptive rendering functionality is supported by the following components:
+
+* [AutoComplete]({%slug autocomplete-overview%})
+* [ComboBox]({%slug components/combobox/overview%})
+* [DatePicker]({%slug components/datepicker/overview%})
+* [DateRangePicker]({%slug daterangepicker-overview%})
+* [DateTimePicker]({%slug components/datetimepicker/overview%})
+* [DropDownList]({%slug components/dropdownlist/overview%})
+* [MultiColumnComboBox]({%slug multicolumncombobox-overview%})
+* [MultiSelect]({%slug multiselect-overview%})
+* [TimePicker]({%slug components/timepicker/overview%})
+
+## Basics
+
+To enable the adaptive rendering use the `AdaptiveMode` parameter. It takes a member of the `AdaptiveMode` enum:
+
+* `None` (default)
+* `Auto`
+
+Optionally, you may set the `Title` parameter to provide custom header text for the popup on small and medium devices.
+
+>caption Enable the adaptive rendering
+
+````CSHTML
+// NOTE: The configurations below includes only the DropDownList, but it is applicable to all of the above listed components
+
+// Adapts to the screen size to use the appropriate rendering.
+<TelerikDropDownList ... AdaptiveMode="@AdaptiveMode.Auto" Title="Select item"... />
+````
+
+# Rendering specifics
+
+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.
+
+Three breakpoints define the rendering options as follows:
+
+@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
+
+|| **Small** | **Medium** | **Large** |
+|-------|-------|--------|-------|
+**Dimensions** | up to 500px | 501px to 768px | over 768px |
+**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. |
+
+## Limitations
+
+* 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`.
+
+## See also
+
+* [Live Demo: AutoComplete](https://demos.telerik.com/blazor-ui/autocomplete/adaptive)
+* [Live Demo: ComboBox](https://demos.telerik.com/blazor-ui/combobox/adaptive)
+* [Live Demo: DatePicker](https://demos.telerik.com/blazor-ui/datepicker/adaptive)
+* [Live Demo: DateRangePicker](https://demos.telerik.com/blazor-ui/daterangepicker/adaptive)
+* [Live Demo: DateTimePicker](https://demos.telerik.com/blazor-ui/datetimepicker/adaptive)
+* [Live Demo: DropDownList](https://demos.telerik.com/blazor-ui/dropdownlist/adaptive)
+* [Live Demo: MultiColumnComboBox](https://demos.telerik.com/blazor-ui/multicolumncombobox/adaptive)
+* [Live Demo: MultiSelect](https://demos.telerik.com/blazor-ui/multiselect/adaptive)
+* [Live Demo: TimePicker](https://demos.telerik.com/blazor-ui/timepicker/adaptive)

components/autocomplete/overview.md

@@ -68,6 +68,10 @@ The Blazor AutoComplete @[template](/_contentTemplates/dropdowns/features.md#gro
 
 @[template](/_contentTemplates/dropdowns/features.md#virtualization) [Read more about the Blazor AutoComplete virtualization...]({% slug autocomplete-virtualization %})
 
+## Adaptive Rendering
+
+@[template](/_contentTemplates/dropdowns/adaptive-rendering.md#intro)
+
 ## Parameters
 
 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
 
 | Parameter    | Type  | Description |
 | ----------- | ----------- | -------|
-| `Data` | `IEnumerable<TItem>` | allows you to provide the data source. Required.
-| `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.
+| `AdaptiveMode` | `AdaptiveMode` <br /> (`None`) | The [adaptive mode]({%slug adaptive-rendering%}) of the component. |
+| `Data` | `IEnumerable<TItem>` | allows you to provide the data source. Required. |
+| `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. |
 | `Enabled` | `bool` | Whether the component is enabled. |
 | `Filterable` | `bool` | Whether [filtering]({%slug multiselect-filter%}) is enabled for the end user (suggestions will get narrowed down as they type). |
 | `FilterOperator` | `StringFilterOperator` <br /> (`StartsWith`) | The string operation that will be used for [filtering]({%slug multiselect-filter%}). |
 | `Id` | `string` | Renders as the `id` attribute on the `<input />` element, so you can attach a `<label for="">` to the input.|
-| `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.|
+| `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. |
+| `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%}). |
 | `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`.|
-| `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.|
-| `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.|
-| `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`.|
-| `Enabled` | `bool`  | Use this Boolean property to render a disabled Blazor AutoComplete component until certain requirements are met.|
-| `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%}).|
-| `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`).|
+| `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. |
+| `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. |
+| `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`. |
+| `Enabled` | `bool`  | Use this Boolean property to render a disabled Blazor AutoComplete component until certain requirements are met. |
+| `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%}). |
+| `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`). |
 
 ### Styling and Appearance
 

components/combobox/custom-value.md

@@ -101,7 +101,9 @@ Selected value: @selectedValue
 }
 ````
 
+## Limitations
 
+* `AllowCustom` is not compatible with [Adaptive rendering]({%slug adaptive-rendering%}).
 
 ## See Also
 

components/combobox/overview.md

@@ -69,6 +69,9 @@ The Blazor ComboBox @[template](/_contentTemplates/dropdowns/features.md#groupin
 
 @[template](/_contentTemplates/dropdowns/features.md#virtualization) [Read more about the Blazor ComboBox virtualization...]({% slug combobox-virtualization %})
 
+## Adaptive Rendering
+
+@[template](/_contentTemplates/dropdowns/adaptive-rendering.md#intro)
 
 ## Parameters
 
@@ -78,21 +81,23 @@ The Blazor ComboBox @[template](/_contentTemplates/dropdowns/features.md#groupin
 
 | Parameter      | Type | Description
 | ----------- | ----------- | -----------|
-| `AllowCustom` | `bool` | whether the user can enter [custom values]({%slug components/combobox/custom-value%}). If enabled, the `ValueField` must be a `string`.
-| `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`.
-| `Data` | `IEnumerable<TItem>` | allows you to provide the data source. Required.
-| `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.
-| `Enabled` | `bool` | whether the component is enabled.
-|`Filterable` | `bool` | whether [filtering]({%slug components/combobox/filter%}) is enabled for the end user.
-| `FilterOperator` | `StringFilterOperator` <br /> (`StartsWith`) | the method of [filtering]({%slug components/combobox/filter%}) the items.
-| `Id` | `string` | renders as the `id` attribute on the `<input />` element, so you can attach a `<label for="">` to the input.
-| `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.
-| `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.
-| `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`|
-| `TextField` | `string` <br /> (`Text`)| the name of the field from the model that will be shown to the user.
-| `ValueField` | `string` <br /> (`Value`) | the name of the field from the model that will be the underlying `value`.
-| `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.
-| `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.
+| `AdaptiveMode` | `AdaptiveMode` <br /> (`None`) | The [adaptive mode]({%slug adaptive-rendering%}) of the component. |
+| `AllowCustom` | `bool` | whether the user can enter [custom values]({%slug components/combobox/custom-value%}). If enabled, the `ValueField` must be a `string`. |
+| `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`. |
+| `Data` | `IEnumerable<TItem>` | allows you to provide the data source. Required. |
+| `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. |
+| `Enabled` | `bool` | whether the component is enabled. |
+|`Filterable` | `bool` | whether [filtering]({%slug components/combobox/filter%}) is enabled for the end user. |
+| `FilterOperator` | `StringFilterOperator` <br /> (`StartsWith`) | the method of [filtering]({%slug components/combobox/filter%}) the items. |
+| `Id` | `string` | renders as the `id` attribute on the `<input />` element, so you can attach a `<label for="">` to the input. |
+| `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. |
+| `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. |
+| `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` |
+| `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%}). |
+| `TextField` | `string` <br /> (`Text`)| the name of the field from the model that will be shown to the user. |
+| `ValueField` | `string` <br /> (`Value`) | the name of the field from the model that will be the underlying `value`. |
+| `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. |
+| `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. |
 
 ### Styling and Appearance