docs(grid,treelist): Improve selection documentation (#2542)

* docs(grid): Improve selection documentation

* docs(TreeList): Improve Selection documentation

Author: dimodi

components/grid/selection/cells.md

@@ -91,6 +91,8 @@ To enable cell selection:
 
 You can respond to user selection actions through the `SelectedCellsChanged` event. The event handler receives a collection of type `IEnumerable<GridSelectedCellDescriptor>`. The collection may have multiple, single, or no objects in it, depending on the `SelectionMode` and the last user selection.
 
+> The `SelectedCellsChanged` event handler cannot be awaited. To execute asynchronous operations when the user selects rows, use the [`OnRowClick`]({%slug grid-events%}#onrowclick) or [`OnRowDoubleClick`]({%slug grid-events%}#onrowdoubleclick) event instead.
+
 >caption Using the Grid SelectedCellsChanged event
 
 ````CSHTML
@@ -170,10 +172,6 @@ You can respond to user selection actions through the `SelectedCellsChanged` eve
 }
 ````
 
-### SelectedCellsChanged and Asynchronous Operations
-
-The `SelectedCellsChanged` event handler cannot be awaited. To execute asynchronous operations when the user selects rows, use the [`OnRowClick`]({%slug grid-events%}#onrowclick) or [`OnRowDoubleClick`]({%slug grid-events%}#onrowdoubleclick) event instead.
-
 ## GridSelectedCellDescriptor
 
 The `GridSelectedCellDescriptor` type exposes the following properties:

components/grid/selection/overview.md

@@ -20,16 +20,7 @@ The Grid component supports row and cell selection. When you select a row or a c
 
 ## Enable Row or Cell Selection
 
-You can configure the Grid either for row or cell selection:
-
-* To enable row selection:
-  * Set the [Grid `SelectionMode` parameter](#use-single-or-multiple-selection) or
-  * Add a `<GridSelectionSettings>` tag to the `<GridSettings>` tag, and set the `SelectionType` parameter to `GridSelectionType.Row`.
-  * Optionally, you can also select rows through the [checkbox column]({%slug components/grid/columns/checkbox%}).
-* To enable cell selection:
-  * Add a `<GridSelectionSettings>` tag to the `<GridSettings>` tag, and set the `SelectionType` parameter to `GridSelectionType.Cell`.
-
-See [Rows Selection Basics]({%slug grid-selection-row%}#basics) and [Cells Selection Basics]({%slug grid-selection-cell%}#basics) for more details.
+You can configure the Grid either for row or cell selection. See [Rows Selection Basics]({%slug grid-selection-row%}#basics) and [Cells Selection Basics]({%slug grid-selection-cell%}#basics) for more details and examples.
 
 ## Use Single or Multiple Selection
 

components/grid/selection/rows.md

@@ -20,7 +20,13 @@ To select a range of rows, hold the **Shift** key, while clicking on the first a
 
 Check the [Grid Keyboard navigation demo](https://demos.telerik.com/blazor-ui/grid/keyboard-navigation) for detailed information about selecting rows with the keyboard.
 
-You can also render a checkbox column that allows users to select and deselect rows. To use checkbox selection, add a [`GridCheckboxColumn`]({%slug components/grid/columns/checkbox%}) in the `GridColumns` collection of the Grid. The `GridCheckboxColumn` provides [additional configuration settings related to selection]({%slug components/grid/columns/checkbox%}#parameters).
+To enable row selection:
+
+1. Define the selection mode through one of the following options:
+    * Set the [Grid `SelectionMode` parameter]({%slug grid-selection-overview%}#use-single-or-multiple-selection), or
+    * Add a `<GridSelectionSettings>` tag inside the Grid `<GridSettings>` tag, and set the `SelectionType` parameter to `GridSelectionType.Row`.
+1. Set the Grid `SelectedItems` parameter to a collection of type `IEnumerable<TItem>` where `TItem` is the Grid model class. The collection must be initialized in advance.
+1. Optionally, add a [checkbox column]({%slug components/grid/columns/checkbox%}) to the `GridColumns` collection of the Grid. The `GridCheckboxColumn` provides [additional configuration settings related to selection]({%slug components/grid/columns/checkbox%}#parameters).
 
 >caption Grid multiple row selection
 
@@ -78,6 +84,8 @@ You can also render a checkbox column that allows users to select and deselect r
 
 You can respond to user selection actions through the `SelectedItemsChanged` event. The event handler receives a collection of the Grid data model. The collection may have multiple, single, or no items in it, depending on the `SelectionMode` and the last user selection.
 
+> The `SelectedItemsChanged` event handler cannot be awaited. To execute asynchronous operations when the user selects rows, use the [`OnRowClick`]({%slug grid-events%}#onrowclick) or [`OnRowDoubleClick`]({%slug grid-events%}#onrowdoubleclick) event instead.
+
 >caption Using the Grid SelectedItemsChanged event
 
 ````CSHTML
@@ -146,10 +154,6 @@ You can respond to user selection actions through the `SelectedItemsChanged` eve
 }
 ````
 
-### SelectedItemsChanged and Asynchronous Operations
-
-The `SelectedItemsChanged` event handler cannot be awaited. To execute asynchronous operations when the user selects rows, use the [`OnRowClick`]({%slug grid-events%}#onrowclick) or [`OnRowDoubleClick`]({%slug grid-events%}#onrowdoubleclick) event instead.
-
 ## Selection When Data Changes
 
 When the Grid `Data` collection changes, the `SelectedItems` collection has the following behavior:

components/treelist/selection/cells.md

@@ -98,6 +98,8 @@ To enable cell selection:
 
 You can respond to user selection actions through the `SelectedCellsChanged` event. The event handler receives a collection of type `IEnumerable<TreeListSelectedCellDescriptor>`. The collection may have multiple, single, or no objects in it, depending on the `SelectionMode` and the last user selection.
 
+> The `SelectedCellsChanged` event handler cannot be awaited. To execute asynchronous operations when the user selects rows, use the [`OnRowClick`]({%slug treelist-events%}#onrowclick) or [`OnRowDoubleClick`]({%slug treelist-events%}#onrowdoubleclick) event instead.
+
 >caption Using the TreeList SelectedCellsChanged event
 
 ````CSHTML
@@ -184,10 +186,6 @@ You can respond to user selection actions through the `SelectedCellsChanged` eve
 }
 ````
 
-### SelectedCellsChanged and Asynchronous Operations
-
-The `SelectedCellsChanged` event handler cannot be awaited. To execute asynchronous operations when the user selects rows, use the [`OnRowClick`]({%slug treelist-events%}#onrowclick) or [`OnRowDoubleClick`]({%slug treelist-events%}#onrowdoubleclick) event instead.
-
 ## TreeListSelectedCellDescriptor
 
 The `TreeListSelectedCellDescriptor` type exposes the following properties:

components/treelist/selection/overview.md

@@ -20,16 +20,7 @@ The TreeList component supports row and cell selection. When you select a row or
 
 ## Enable Row or Cell Selection
 
-You can configure the TreeList either for row or cell selection:
-
-* To enable row selection:
-  * Set the [TreeList `SelectionMode` parameter](#use-single-or-multiple-selection) or
-  * Add a `<TreeListSelectionSettings>` tag to the `<TreeListSettings>` tag, and set the `SelectionType` parameter to `TreeListSelectionType.Row`.
-  * Optionally, you can also select rows through the [checkbox column]({%slug treelist-columns-checkbox%}).
-* To enable cell selection:
-  * Add a `<TreeListSelectionSettings>` tag to the `<TreeListSettings>` tag, and set the `SelectionType` parameter to `TreeListSelectionType.Cell`.
-
-See [Row Selection Basics]({%slug treelist-selection-row%}#basics) and [Cell Selection Basics]({%slug treelist-selection-cell%}#basics) for more details.
+You can configure the TreeList either for row or cell selection. See [Row Selection Basics]({%slug treelist-selection-row%}#basics) and [Cell Selection Basics]({%slug treelist-selection-cell%}#basics) for more details and examples.
 
 ## Use Single or Multiple Selection
 

components/treelist/selection/rows.md

@@ -20,7 +20,13 @@ To select a range of rows, hold the **Shift** key, while clicking on the first a
 
 Check the [TreeList Keyboard navigation demo](https://demos.telerik.com/blazor-ui/treelist/keyboard-navigation) for detailed information about selecting rows with the keyboard.
 
-You can also render a checkbox column that allows users to select and deselect rows. To use checkbox selection, add a [`TreeListCheckboxColumn`]({%slug treelist-columns-checkbox%}) in the `TreeListColumns` collection of the TreeList. The `TreeListCheckboxColumn` provides [additional configuration settings related to selection]({%slug treelist-columns-checkbox%}#parameters).
+To enable row selection:
+
+1. Define the selection mode through one of the following options:
+    * Set the [TreeList `SelectionMode` parameter]({%slug treelist-selection-overview%}#use-single-or-multiple-selection), or
+    * Add a `<TreeListSelectionSettings>` tag to the `<TreeListSettings>` tag, and set the `SelectionType` parameter to `TreeListSelectionType.Row`.
+1. Set the TreeList `SelectedItems` parameter to a collection of type `IEnumerable<TItem>` where `TItem` is the TreeList model class. The collection must be initialized in advance.
+1. Optionally, add a [checkbox column]({%slug treelist-columns-checkbox%}) to the `TreeListColumns` collection of the TreeList. The `TreeListCheckboxColumn` provides [additional configuration settings related to selection]({%slug treelist-columns-checkbox%}#parameters).
 
 >caption TreeList multiple row selection
 
@@ -85,6 +91,8 @@ You can also render a checkbox column that allows users to select and deselect r
 
 You can respond to user selection actions through the `SelectedItemsChanged` event. The event handler receives a collection of the TreeList data model. The collection may have multiple, single, or no items in it, depending on the `SelectionMode` and the last user selection.
 
+> The `SelectedItemsChanged` event handler cannot be awaited. To execute asynchronous operations when the user selects rows, use the [`OnRowClick`]({%slug treelist-events%}#onrowclick) or [`OnRowDoubleClick`]({%slug treelist-events%}#onrowdoubleclick) event instead.
+
 >caption Using the TreeList SelectedItemsChanged event
 
 ````CSHTML
@@ -159,10 +167,6 @@ You can respond to user selection actions through the `SelectedItemsChanged` eve
 }
 ````
 
-### SelectedItemsChanged and Asynchronous Operations
-
-The `SelectedItemsChanged` event handler cannot be awaited. To execute asynchronous operations when the user selects rows, use the [`OnRowClick`]({%slug treelist-events%}#onrowclick) or [`OnRowDoubleClick`]({%slug treelist-events%}#onrowdoubleclick) event instead.
-
 ## Selection When Data Changes
 
 When the TreeList `Data` collection changes, the `SelectedItems` collection has the following behavior: