docs(Grid,TreeList): Revamp Virtual Scrolling documentation

components/grid/manual-operations.md

@@ -29,6 +29,7 @@ Examples:
 * [Telerik .ToDataSourceResult(request)](#telerik-todatasourceresult-request)
 * [Grouping with OnRead](#grouping-with-onread)
 * [Aggregates with OnRead](#aggregates-with-onread)
+* [Virtual Scrolling with OnRead](#virtual-scrolling-with-onread)
 * [Get Information From the DataSourceRequest](#get-information-from-the-datasourcerequest)
 * [Use OData Service](https://github.com/telerik/blazor-ui/tree/master/grid/odata)
 * [Serialize the DataSoureRequest to the server](https://github.com/telerik/blazor-ui/tree/master/grid/datasourcerequest-on-server)
@@ -277,9 +278,7 @@ This sample shows how to set up the grid to use grouping with manual data source
 
 When using [aggregates](slug:grid-aggregates) with `OnRead`, the Grid expects you to set one more property of the `GridReadEventArgs` object - `AggregateResults`. Otherwise the component will show aggregate values for the current page only.
 
-<div class="skip-repl"></div>
-
-````CS
+````C#.skip-repl
 private async Task OnGridRead(GridReadEventArgs args)
 {
     DataSourceResult result = AllGridData.ToDataSourceResult(args.Request);
@@ -290,6 +289,19 @@ private async Task OnGridRead(GridReadEventArgs args)
 }
 ````
 
+## Virtual Scrolling with OnRead
+
+When using [virtual Grid scrolling](slug:components/grid/virtual-scrolling), get the values of `args.Request.Skip` and `args.Request.PageSize` to determine the current Grid scroll offset and load the correct data items. Do not use `args.Request.Page` with virtual scrolling, because it is always `1`.
+
+````C#.skip-repl
+private List<Product> GridData { get; set; } = new();
+
+private async Task OnGridRead(GridReadEventArgs args)
+{
+    args.Data = GridData.Skip(args.Request.Skip).Take(args.Request.PageSize);
+    args.Total = GridData.Count;
+}
+````
 
 ## Get Information From the DataSourceRequest
 

components/treelist/virtual-scrolling.md

@@ -3,93 +3,179 @@ title: Virtual Scrolling
 page_title: TreeList - Virtual Scrolling
 description: Enable and configure the virtual scrolling of rows in the TreeList for Blazor.
 slug: treelist-virtual-scrolling
-tags: telerik,blazor,treelist,virtual,rows,scrolling
+tags: telerik,blazor,treelist,virtual,scrolling
 published: True
 position: 25
 ---
 
 # TreeList Virtual Scrolling
 
+The TreeList virtual scrolling feature allows users to scroll vertically through all records in the data source. The feature is an alternative to paging.
 
-Virtual scrolling provides an alternative to paging. Instead of utilizing a pager, the user scrolls vertically through all records in the data source.
+To enhance the rendering performance, the TreeList reuses the same set of HTML elements. Loading indicators (skeletons) appear in the table cells during scrolling and data loading. If the user scrolls back up after scrolling down to the next set of rows, the previous data reloads from the data source, similar to regular paging, with the scroll distance determining the data to be loaded.
 
-To enhance rendering performance, the TreeList reuses the same set of HTML elements. As the next data loads, a loading indicator appears on the cells. If the user scrolls back up after scrolling down to the next set of rows, the previous data reloads from the data source, similar to regular paging, with the scroll distance determining the data to be loaded.
+You can also use the [Blazor TreeList virtualization for the TreeList columns](slug:treelist-columns-virtual).
 
 ## Using Virtual Scrolling
 
-* Set the `ScrollMode` parameter to `TreeListScrollMode.Virtual` (the default value is `Scrollable`).
-* Set the `Height` and `RowHeight` parameters.
+To enable Blazor TreeList row virtualization:
 
->caption Enable virtual scrolling in the Telerik TreeList for Blazor
+1. Set the `ScrollMode` parameter to `TreeListScrollMode.Virtual` (the default value is `Scrollable`).
+1. [Set the `Height` parameter](#height) to a `string` CSS value.
+1. [Set the `RowHeight` parameter](#rowheight) to a `decimal` value that denotes pixels.
+1. [Set the `PageSize` parameter](#pagesize).
+
+> The values of the `Height`, `RowHeight`, and `PageSize` parameters are related to one another. The following sections explain how.
+
+## Height
+
+Set the TreeList `Height` parameter to any [valid `string` CSS value](slug:common-features/dimensions), for example, `px`, `%`, `em`, or `vh`. If the TreeList should expand vertically, accoding to the available space, then check the article [Adjust Grid Height to Match the Browser Viewport Height](slug:grid-kb-adjust-height-with-browser).
+
+Set the `Height` value, so that users can't see the whole [`PageSize` of items](#pagesize) at once. Otherwise, empty row skeletons may display in the TreeList while users are not scrolling.
+
+## PageSize
+
+Set the TreeList `PageSize` parameter to an `int` value. The `PageSize` determines how many table rows are populated and rendered at any given time.
+
+Set the `PageSize` value, so that the rendered table rows do fit in the [TreeList height](#height). At least one table row must be completely invisible. Otherwise, empty row skeletons may display in the TreeList while users are not scrolling. The exact `PageSize` value allows you to balance between better user experience and rendering efficiency:
+
+* A larger `PageSize` value will make the TreeList display empty row skeletons more rarely while users are scrolling down. At the same time, the TreeList may be re-rendering the same data items repetitively if the user scrolls just a little.
+* A smaller `PageSize` will make the TreeList render a smaller number of items on each user scroll. At the same time, users will see row skeletons sooner or more frequently during scrolling.
+
+## RowHeight
+
+Set the `RowHeight` parameter to a `decimal` value. The TreeList uses it to set an inline `height` style in pixels to all TreeList table rows (`<tr>`).
+
+The `RowHeight` value must be large enough to accommodate the cell content in all rows, even if the content differs. In other words, the `RowHeight` setting must apply the same or greater table row height than what the browser would normally render. The effective row height depends on:
+
+* The cell content and text wrapping
+* The CSS theme, including font size, line height, and cell paddings.
+
+For example, the following list shows the minimum valid `RowHeight` values when using the [built-in CSS themes](slug:themes-overview), single-line plain text content, and no command buttons:
+
+* `36` for the Default theme (`14px` font size, `20px` line height, and 2 * `8px` vertical paddings)
+* `40` for the Bootstrap theme (`16px` font size, `24px` line height, and 2 * `8px` vertical paddings)
+* `48` for the Material theme (`14px` font size, `28px` line height, and 2 * `10px` vertical paddings)
+* `44` for the Fluent theme (`14px` font size, `20px` font size and 2 * `12px` vertical paddings)
+
+> Browsers treat table row `height` styles as `min-height` styles. If the table row content cannot fit in the set `RowHeight`, the browser expands the table row. The TreeList configuration must not allow this to happen. It is crucial that all TreeList table rows display with the same effective height when using virtial scrolling, otherwise the virtual scrolling experience will break.
+
+The `RowHeight` parameter value cannot change at runtime, unless the application recreates the whole TreeList component by removing it from the web page temporarily.
+
+If necessary, you can also use the `RowHeight` parameter without virtual row scrolling.
+
+## Limitations
+
+There is a [browser limitation, which affects the maximum number of data items in a virtual TreeList](slug:grid-kb-virtualization-many-records). The problem occurs with millions of items and you can partially mitigate it by [changing the TreeList styles to make the row height smaller](slug:grid-kb-reduce-row-height).
+
+In addition to virtual scrolling, another approach to optimize the rendering performance is to use [TreeList paging](slug:treelist-paging).
+
+## Example
+
+>caption Virtual TreeList scrolling
 
 ````RAZOR
 <TelerikTreeList Data="@TreeListData"
-                 ScrollMode="@TreeListScrollMode.Virtual"
-                 Height="500px"
-                 RowHeight="50"
                  IdField="@nameof(Employee.Id)"
                  ParentIdField="@nameof(Employee.ParentId)"
-                 Sortable="true"
-                 FilterMode="@TreeListFilterMode.FilterMenu">
+                 FilterMode="TreeListFilterMode.FilterMenu"
+                 Height="360px"
+                 PageSize="20"
+                 RowHeight="40"
+                 ScrollMode="@TreeListScrollMode.Virtual"
+                 Sortable="true">
     <TreeListColumns>
-        <TreeListColumn Expandable="true" Field="FirstName" Title="First Name" />
-        <TreeListColumn Field="LastName" Title="Last Name" />
-        <TreeListColumn Field="Position" />
+        <TreeListColumn Field="@nameof(Employee.Name)" Expandable="true" />
+        <TreeListColumn Field="@nameof(Employee.Salary)" DisplayFormat="{0:C2}" Width="160px" />
+        <TreeListColumn Field="@nameof(Employee.HireDate)" DisplayFormat="{0:d}" Width="160px" />
+        <TreeListColumn Field="@nameof(Employee.IsDriver)" Width="120px" />
     </TreeListColumns>
 </TelerikTreeList>
 
 @code {
-    private List<Employee> TreeListData { get; set; } = new();
+    private List<Employee>? TreeListData { get; set; }
 
-    protected override void OnInitialized()
-    {
-        for (int i = 1; i <= 1000; i++)
-        {
-            TreeListData.Add(new Employee()
-                {
-                    Id = i,
-                    ParentId = i <= 3 ? null : i % 3 + 1,
-                    FirstName = "First " + i,
-                    LastName = "Last " + i,
-                    Position = i <= 3 ? "Team Lead" : "Software Engineer"
-                });
-        }
+    private EmployeeService TreeListEmployeeService { get; set; } = new(treeLevelCount: 3, rootItemCount: 10, childItemCount: 20);
 
-        base.OnInitialized();
+    protected override async Task OnInitializedAsync()
+    {
+        TreeListData = await TreeListEmployeeService.Read();
     }
 
     public class Employee
     {
         public int Id { get; set; }
         public int? ParentId { get; set; }
-        public string FirstName { get; set; }
-        public string LastName { get; set; }
-        public string Position { get; set; }
+        public bool HasChildren { get; set; }
+        public string Name { get; set; } = string.Empty;
+        public decimal? Salary { get; set; }
+        public DateTime? HireDate { get; set; }
+        public bool IsDriver { get; set; }
     }
-}
-````
-
-## Notes
 
-There are several things to keep in mind when using virtual scrolling:
+    #region Data Service
 
-* The `RowHeight` is a decimal value that is always interpreted as pixels. The TreeList `Height` does not have to be in pixels, but it may help you calculate the `PageSize` (see below).
+    public class EmployeeService
+    {
+        private List<Employee> Items { get; set; } = new();
 
-    * If the row/cell height the browser renders is larger than the `RowHeight` value, the browser will ignore it. It can depend on the chosen Theme, other CSS rules, or cell data that occupies more than one row. Inspect the rendered HTML to make sure the grid setting matches the rendering.
+        private readonly int TreeLevelCount;
+        private readonly int RootItemCount;
+        private readonly int ChildItemCount;
 
-        The default TreeList rendering has padding in the cells, and the loading sign has a line height set in order to render. This may impose some minimum heights that can vary with the theme and/or custom styles on the page.
+        private int LastId { get; set; }
+        private Random Rnd { get; set; } = Random.Shared;
 
-    * The `RowHeight` must not change at runtime, because the new dimensions will cause issues with the scrolling logic.
+        public async Task<List<Employee>> Read()
+        {
+            await SimulateAsyncOperation();
+            return Items;
+        }
 
-    * Browser zoom or monitor DPI settings can cause the browser to render different dimensions than the expected and/or non-integer values, which can break the virtualization logic.
+        private async Task SimulateAsyncOperation()
+        {
+            await Task.Delay(100);
+        }
 
-* Do not mix virtualization with paging, as they are alternatives to the same feature.
+        private void PopulateChildren(List<Employee> items, int? parentId, int level)
+        {
+            int itemCount = level == 1 ? RootItemCount : ChildItemCount;
+            for (int i = 1; i <= itemCount; i++)
+            {
+                int itemId = ++LastId;
+                items.Add(new Employee()
+                {
+                    Id = itemId,
+                    ParentId = parentId,
+                    HasChildren = level < TreeLevelCount,
+                    Name = $"Employee Name {itemId}", // {level}-{i}
+                    Salary = Rnd.Next(1_000, 10_000) * 1.23m,
+                    HireDate = DateTime.Today.AddDays(-Rnd.Next(365, 3650)),
+                    IsDriver = itemId % 2 == 0
+                });
+                if (level < TreeLevelCount)
+                {
+                    PopulateChildren(items, itemId, level + 1);
+                }
+            }
+        }
 
-* Provide for a `PageSize` of the TreeList that is large enough, so that the loaded table rows do not fit in the scrollable data area, otherwise the vertical virtual scrollbar will not be created and scrolling will not work. To do this, take into account the `Height` of the TreeList and the `RowHeight`.
+        public EmployeeService(int treeLevelCount = 3, int rootItemCount = 3, int childItemCount = 2)
+        {
+            TreeLevelCount = treeLevelCount;
+            RootItemCount = rootItemCount;
+            ChildItemCount = childItemCount;
+            List<Employee> items = new();
+            PopulateChildren(items, null, 1);
+            Items = items;
+        }
+    }
 
-    * The `PageSize` controls how many rows are rendered at any given time, and how many items are requested from the data source when loading data on demand. You should avoid setting large page sizes, you need to only fill up the TreeList data viewport.
+    #endregion Data Service
+}
+````
 
 ## See Also
 
-  * [Live Demo: TreeList Virtual Scrolling](https://demos.telerik.com/blazor-ui/treelist/virtual-scrolling)
-   
+* [Live Demo: TreeList Virtual Scrolling](https://demos.telerik.com/blazor-ui/treelist/virtual-scrolling)
+* [How to Disable Row Placeholders During Virtual Scrolling](slug:grid-kb-hide-virtual-row-skeletons)

knowledge-base/grid-hide-virtual-row-skeletons.md

@@ -0,0 +1,88 @@
+---
+title: Hide Grid Virtual Row Skeletons
+description: Learn how to hide / remove / disable the Grid and TreeList cell placeholder skeletons during virtual row scrolling.
+type: how-to
+page_title: How To Hide Row Skeletons During Virtual Grid Scrolling
+slug: grid-kb-hide-virtual-row-skeletons
+tags: blazor, grid, treelist, skeleton, styles, css
+ticketid: 1658135, 1642794
+res_type: kb
+---
+
+## Environment
+
+<table>
+    <tbody>
+        <tr>
+            <td>Product</td>
+            <td>Grid for Blazor, <br /> TreeList for Blazor</td>
+        </tr>
+    </tbody>
+</table>
+
+## Description
+
+This KB article answers the following questions:
+
+* How to remove the Grid row placeholders during virtual scrolling?
+* How to hide the skeletons that appear in empty table cells during virtual scrolling?
+* How to disable the Grid cell placeholders?
+* How to turn off the Grid loader indicators inside the virtual rows?
+
+## Solution
+
+Apply a `display:none` or `visibility:hidden` CSS style to the `.k-skeleton` selector inside Grid table cells.
+
+>caption Removing placeholder skeletons during virtual Grid scrolling
+
+````RAZOR
+<TelerikGrid Data="@GridData"
+             Height="360px"
+             PageSize="20"
+             RowHeight="40"
+             ScrollMode="@GridScrollMode.Virtual"
+             Class="no-skeletons">
+    <GridColumns>
+        <GridColumn Field="@nameof(Product.Name)" />
+        <GridColumn Field="@nameof(Product.Price)" DisplayFormat="{0:c2}" />
+        <GridColumn Field="@nameof(Product.Quantity)" />
+    </GridColumns>
+</TelerikGrid>
+
+<style>
+    .no-skeletons .k-table-td > .k-skeleton {
+        display: none;
+    }
+</style>
+
+@code {
+    private List<Product> GridData { get; set; } = new();
+
+    protected override void OnInitialized()
+    {
+        for (int i = 1; i <= 1000; i++)
+        {
+            GridData.Add(new Product()
+            {
+                Id = i,
+                Name = $"Name {i}",
+                Price = Random.Shared.Next(1, 100) * 1.23m,
+                Quantity = Random.Shared.Next(0, 1000)
+            });
+        }
+    }
+
+    public class Product
+    {
+        public int Id { get; set; }
+        public string Name { get; set; } = string.Empty;
+        public decimal Price { get; set; }
+        public int Quantity { get; set; }
+    }
+}
+````
+
+## See Also
+
+* [Virtual Grid Scrolling](slug:components/grid/virtual-scrolling)
+* [Virtual TreeList Scrolling](slug:treelist-virtual-scrolling)