Merge pull request #366 from telerik/selects-grouping

dimodi · web-flow · commit 14c85b466d15 · 2021-06-21T17:30:31.000+03:00
docs: document AutoComplete, ComboBox and DropDownList grouping
diff --git a/components/autocomplete/data-bind.md b/components/autocomplete/data-bind.md
@@ -5,7 +5,7 @@ description: Data Binding the AutoComplete for Blazor.
 slug: autocomplete-databind
 tags: telerik,blazor,autocomplete,data,bind,binding,databind
 published: True
-position: 1
+position: 5
 ---
 
 # AutoComplete Data Binding
diff --git a/components/autocomplete/events.md b/components/autocomplete/events.md
@@ -5,7 +5,7 @@ description: Events in the AutoComplete for Blazor.
 slug: autocomplete-events
 tags: telerik,blazor,autocomplete,events
 published: true
-position: 20
+position: 35
 ---
 
 # AutoComplete Events
diff --git a/components/autocomplete/filter.md b/components/autocomplete/filter.md
@@ -5,7 +5,7 @@ description: Filtering in the ComboBox for Blazor.
 slug: autocomplete-filter
 tags: telerik,blazor,combo,autocomplete,filter
 published: True
-position: 3
+position: 10
 ---
 
 # AutoComplete Filter
diff --git a/components/autocomplete/grouping.md b/components/autocomplete/grouping.md
@@ -0,0 +1,77 @@
+---
+title: Grouping
+page_title: AutoComplete - Grouping
+description: Grouping in the AutoComplete for Blazor.
+slug: components/autocomplete/grouping
+tags: telerik,blazor,autocomplete,group,grouping
+published: True
+position: 15
+---
+
+# AutoComplete Grouping
+
+The AutoComplete component allows users to see the listed items grouped in categories. This can improve the user experience and make browsing through the items faster.
+
+To enable AutoComplete grouping, set the `GroupField` parameter to a field name from the model. The AutoComplete will display the corresponding field values as group headers in the dropdown. Nested values of complex object properties are supported (see the example below).
+
+The group headers can stick to the top of the dropdown during scrolling. In other words, users will always know which is the group of the current topmost items in the scrollable list.
+
+>caption Grouping in the AutoComplete
+
+````CSHTML
+<TelerikAutoComplete Data="@Data"
+                 @bind-Value="@SelectedValue"
+                 GroupField="Category.CategoryName"
+                 TextField="ProductName"
+                 ValueField="ProductId"
+                 Placeholder="Select a product">
+</TelerikAutoComplete>
+
+@code {
+    public List<Product> Data { get; set; }
+    public int? SelectedValue { get; set; }
+
+    protected override void OnInitialized()
+    {
+        List<Product> products = new List<Product>();
+        for (int i = 0; i < 20; i++)
+        {
+            products.Add(new Product()
+            {
+                ProductId = i,
+                ProductName = $"Product {i}",
+                Category = new Category() { CategoryId = i % 5, CategoryName = $"Category {i % 5}" }
+            });
+        }
+
+        Data = products;
+
+        base.OnInitialized();
+    }
+
+    public class Product
+    {
+        public int ProductId { get; set; }
+        public string ProductName { get; set; }
+        public Category Category { get; set; }
+    }
+
+    public class Category
+    {
+        public int CategoryId { get; set; }
+        public string CategoryName { get; set; }
+    }
+}
+````
+
+# Notes
+
+* One level of grouping is supported.
+* The `DefaultItem` (e.g. "Select item...") is always rendered above the sticky group header in the dropdown.
+* A grouped AutoComplete will provide a `Groups` property with a single [`GroupDescriptor`](https://docs.telerik.com/blazor-ui/api/Telerik.DataSource.GroupDescriptor) in the [`DataSourceRequest`](https://docs.telerik.com/blazor-ui/api/Telerik.DataSource.DataSourceRequest) argument of its [OnRead event]({%slug components/autocomplete/events%}#onread). This will allow the developer to apply grouping with [manual data operations]({%slug components/grid/manual-operations%}).
+* `GroupHeaderTemplate` and `GroupItemTemplate` will be introduced in a future version. Currently there is a bug in the Blazor framework that prevents us from supporting them.
+* Virtual scrolling with grouping will be supported in a future version.
+
+## See Also
+
+  * [Live Demo: AutoComplete Grouping](https://demos.telerik.com/blazor-ui/autocomplete/grouping)
diff --git a/components/autocomplete/refresh-data.md b/components/autocomplete/refresh-data.md
@@ -5,7 +5,7 @@ description: Refresh Autocomplete Data using Observable Data or creating a new C
 slug: autocomplete-refresh-data
 tags: telerik,blazor,autocomplete,observable,data,new,collection
 published: True
-position: 15
+position: 30
 ---
 
 # Autocomplete - Refresh Data
diff --git a/components/autocomplete/templates.md b/components/autocomplete/templates.md
@@ -5,7 +5,7 @@ description: Templates in the AutoComplete for Blazor.
 slug: autocomplete-templates
 tags: telerik,blazor,combo,autocomplete,templates
 published: True
-position: 5
+position: 20
 ---
 
 # AutoComplete Templates
diff --git a/components/autocomplete/virtualization.md b/components/autocomplete/virtualization.md
@@ -5,7 +5,7 @@ description: UI virtualization to allow large data sources in the AutoComplete f
 slug: autocomplete-virtualization
 tags: telerik,blazor,AutoComplete,virtualization
 published: True
-position: 5
+position: 25
 ---
 
 # AutoComplete Virtualization
diff --git a/components/combobox/custom-value.md b/components/combobox/custom-value.md
@@ -5,7 +5,7 @@ description: Custom values and user input in the ComboBox for Blazor.
 slug: components/combobox/custom-value
 tags: telerik,blazor,combo,combobox,custom,value,input
 published: True
-position: 4
+position: 20
 ---
 
 # ComboBox Custom Values
diff --git a/components/combobox/data-bind.md b/components/combobox/data-bind.md
@@ -5,7 +5,7 @@ description: Data Binding the ComboBox for Blazor.
 slug: components/combobox/databind
 tags: telerik,blazor,combobox,combo,data,bind,binding,databind
 published: True
-position: 1
+position: 5
 ---
 
 # ComboBox Data Binding
diff --git a/components/combobox/events.md b/components/combobox/events.md
@@ -5,7 +5,7 @@ description: Events in the ComboBox for Blazor.
 slug: components/combobox/events
 tags: telerik,blazor,combobox,combo,events
 published: true
-position: 20
+position: 40
 ---
 
 # ComboBox Events
diff --git a/components/combobox/filter.md b/components/combobox/filter.md
@@ -5,7 +5,7 @@ description: Filtering in the ComboBox for Blazor.
 slug: components/combobox/filter
 tags: telerik,blazor,combo,combobox,filter
 published: True
-position: 3
+position: 10
 ---
 
 # ComboBox Filter
diff --git a/components/combobox/grouping.md b/components/combobox/grouping.md
@@ -0,0 +1,77 @@
+---
+title: Grouping
+page_title: ComboBox - Grouping
+description: Grouping in the ComboBox for Blazor.
+slug: components/combobox/grouping
+tags: telerik,blazor,combo,combobox,group,grouping
+published: True
+position: 15
+---
+
+# ComboBox Grouping
+
+The ComboBox component allows users to see the listed items grouped in categories. This can improve the user experience and make browsing through the items faster.
+
+To enable ComboBox grouping, set the `GroupField` parameter to a field name from the model. The ComboBox will display the corresponding field values as group headers in the dropdown. Nested values of complex object properties are supported (see the example below).
+
+The group headers can stick to the top of the dropdown during scrolling. In other words, users will always know which is the group of the current topmost items in the scrollable list.
+
+>caption Grouping in the ComboBox
+
+````CSHTML
+<TelerikComboBox Data="@Data"
+                 @bind-Value="@SelectedValue"
+                 GroupField="Category.CategoryName"
+                 TextField="ProductName"
+                 ValueField="ProductId"
+                 Placeholder="Select a product">
+</TelerikComboBox>
+
+@code {
+    public List<Product> Data { get; set; }
+    public int? SelectedValue { get; set; }
+
+    protected override void OnInitialized()
+    {
+        List<Product> products = new List<Product>();
+        for (int i = 0; i < 20; i++)
+        {
+            products.Add(new Product()
+            {
+                ProductId = i,
+                ProductName = $"Product {i}",
+                Category = new Category() { CategoryId = i % 5, CategoryName = $"Category {i % 5}" }
+            });
+        }
+
+        Data = products;
+
+        base.OnInitialized();
+    }
+
+    public class Product
+    {
+        public int ProductId { get; set; }
+        public string ProductName { get; set; }
+        public Category Category { get; set; }
+    }
+
+    public class Category
+    {
+        public int CategoryId { get; set; }
+        public string CategoryName { get; set; }
+    }
+}
+````
+
+# Notes
+
+* One level of grouping is supported.
+* The `DefaultItem` (e.g. "Select item...") is always rendered above the sticky group header in the dropdown.
+* A grouped ComboBox will provide a `Groups` property with a single [`GroupDescriptor`](https://docs.telerik.com/blazor-ui/api/Telerik.DataSource.GroupDescriptor) in the [`DataSourceRequest`](https://docs.telerik.com/blazor-ui/api/Telerik.DataSource.DataSourceRequest) argument of its [OnRead event]({%slug components/combobox/events%}#onread). This will allow the developer to apply grouping with [manual data operations]({%slug components/grid/manual-operations%}).
+* `GroupHeaderTemplate` and `GroupItemTemplate` will be introduced in a future version. Currently there is a bug in the Blazor framework that prevents us from supporting them.
+* Virtual scrolling with grouping will be supported in a future version.
+
+## See Also
+
+  * [Live Demo: ComboBox Grouping](https://demos.telerik.com/blazor-ui/combobox/grouping)
diff --git a/components/combobox/refresh-data.md b/components/combobox/refresh-data.md
@@ -5,7 +5,7 @@ description: Refresh ComboBox Data using Observable Data or creating a new Colle
 slug: combobox-refresh-data
 tags: telerik,blazor,combobox,observable,data,new,collection
 published: True
-position: 15
+position: 35
 ---
 
 # ComboBox - Refresh Data
diff --git a/components/combobox/templates.md b/components/combobox/templates.md
@@ -5,7 +5,7 @@ description: Templates in the ComboBox for Blazor.
 slug: components/combobox/templates
 tags: telerik,blazor,combo,combobox,templates
 published: True
-position: 5
+position: 25
 ---
 
 # ComboBox Templates
diff --git a/components/combobox/virtualization.md b/components/combobox/virtualization.md
@@ -5,7 +5,7 @@ description: UI virtualization to allow large data sources in the ComboBox for B
 slug: combobox-virtualization
 tags: telerik,blazor,combo,combobox,virtualization
 published: True
-position: 5
+position: 30
 ---
 
 # ComboBox Virtualization
diff --git a/components/dropdownlist/data-bind.md b/components/dropdownlist/data-bind.md
@@ -5,7 +5,7 @@ description: Data Binding the DropdownList for Blazor.
 slug: components/dropdownlist/databind
 tags: telerik,blazor,dropdownlist,dropdown,list,data,bind,binding,databind
 published: True
-position: 1
+position: 5
 ---
 
 # DropDownList Data Binding
diff --git a/components/dropdownlist/events.md b/components/dropdownlist/events.md
@@ -5,7 +5,7 @@ description: Events in the DropDownList for Blazor.
 slug: components/dropdownlist/events
 tags: telerik,blazor,dropdown,list,dropdownlist,events
 published: true
-position: 20
+position: 35
 ---
 
 # Events
diff --git a/components/dropdownlist/filter.md b/components/dropdownlist/filter.md
@@ -5,7 +5,7 @@ description: Filtering in the DropDownList for Blazor.
 slug: components/dropdownlist/filter
 tags: telerik,blazor,drop,down,list,dropdownlist,filter
 published: True
-position: 5
+position: 10
 ---
 
 # DropDownList Filter
diff --git a/components/dropdownlist/grouping.md b/components/dropdownlist/grouping.md
@@ -0,0 +1,77 @@
+---
+title: Grouping
+page_title: DropDownList - Grouping
+description: Grouping in the DropDownList for Blazor.
+slug: components/dropdownlist/grouping
+tags: telerik,blazor,dropdown,dropdownlist,group,grouping
+published: True
+position: 15
+---
+
+# DropDownList Grouping
+
+The DropDownList component allows users to see the listed items grouped in categories. This can improve the user experience and make browsing through the items faster.
+
+To enable DropDownList grouping, set the `GroupField` parameter to a field name from the model. The DropDownList will display the corresponding field values as group headers in the dropdown. Nested values of complex object properties are supported (see the example below).
+
+The group headers can stick to the top of the dropdown during scrolling. In other words, users will always know which is the group of the current topmost items in the scrollable list.
+
+>caption Grouping in the DropDownList
+
+````CSHTML
+<TelerikDropDownList Data="@Data"
+                 @bind-Value="@SelectedValue"
+                 GroupField="Category.CategoryName"
+                 TextField="ProductName"
+                 ValueField="ProductId"
+                 Placeholder="Select a product">
+</TelerikDropDownList>
+
+@code {
+    public List<Product> Data { get; set; }
+    public int? SelectedValue { get; set; }
+
+    protected override void OnInitialized()
+    {
+        List<Product> products = new List<Product>();
+        for (int i = 0; i < 20; i++)
+        {
+            products.Add(new Product()
+            {
+                ProductId = i,
+                ProductName = $"Product {i}",
+                Category = new Category() { CategoryId = i % 5, CategoryName = $"Category {i % 5}" }
+            });
+        }
+
+        Data = products;
+
+        base.OnInitialized();
+    }
+
+    public class Product
+    {
+        public int ProductId { get; set; }
+        public string ProductName { get; set; }
+        public Category Category { get; set; }
+    }
+
+    public class Category
+    {
+        public int CategoryId { get; set; }
+        public string CategoryName { get; set; }
+    }
+}
+````
+
+# Notes
+
+* One level of grouping is supported.
+* The `DefaultItem` (e.g. "Select item...") is always rendered above the sticky group header in the dropdown.
+* A grouped DropDownList will provide a `Groups` property with a single [`GroupDescriptor`](https://docs.telerik.com/blazor-ui/api/Telerik.DataSource.GroupDescriptor) in the [`DataSourceRequest`](https://docs.telerik.com/blazor-ui/api/Telerik.DataSource.DataSourceRequest) argument of its [OnRead event]({%slug components/dropdownlist/events%}#onread). This will allow the developer to apply grouping with [manual data operations]({%slug components/grid/manual-operations%}).
+* `GroupHeaderTemplate` and `GroupItemTemplate` will be introduced in a future version. Currently there is a bug in the Blazor framework that prevents us from supporting them.
+* Virtual scrolling with grouping will be supported in a future version.
+
+## See Also
+
+  * [Live Demo: DropDownList Grouping](https://demos.telerik.com/blazor-ui/dropdownlist/grouping)
diff --git a/components/dropdownlist/refresh-data.md b/components/dropdownlist/refresh-data.md
@@ -5,7 +5,7 @@ description: Refresh DropDownList Data using Observable Data or creating a new C
 slug: dropdownlist-refresh-data
 tags: telerik,blazor,dropdownlist,observable,data,new,collection
 published: True
-position: 15
+position: 30
 ---
 
 # DropDownList - Refresh Data
diff --git a/components/dropdownlist/templates.md b/components/dropdownlist/templates.md
@@ -5,7 +5,7 @@ description: Templates in the DropdownList for Blazor.
 slug: components/dropdownlist/templates
 tags: telerik,blazor,dropdownlist,dropdown,list,templates
 published: True
-position: 7
+position: 25
 ---
 
 # DropDownList Templates
diff --git a/components/dropdownlist/virtualization.md b/components/dropdownlist/virtualization.md
