docs(grid): aggregates (wip)

Author: marin-bratanov

components/grid/aggregates.md

@@ -20,39 +20,68 @@ There are several available aggregate functions under the `Telerik.Blazor.GridAg
 * `Min`
 * `Sum`
 
+The `Count` aggregate can be applied to any type of field. The other aggregates can only be applied to numerical fields (e.g., `int`, `decimal`, `double`, etc.).
+
+You can use aggregates in the following templates:
+
+* `GroupFooterTemplate` of a `GridColumn` - a footer in the respective column that renders when the grid is grouped.
+* `GroupHeaderTemplate` of a `GridColumn` - a header in the respective column that renders when the grid is grouped by that column. The `Value` field in the context carries the current group value.
+
 To enable aggregates:
 
 1. Set the grid's `Groupable` property to `true`.
 1. Under the `GridAggregates` tag, define the `GridAggregate` entries to enable the aggregations per field you want to use.
-1. Use the aggregate result in the templates that support it by casting their `context` to a `GridGroupAggregateResult`:
-
-    * `GroupFooterTemplate` - a footer in the respective column that renders when the grid is grouped.
+1. Use the aggregate result in the templates that support it - their `context` is strongly typed and carries the aggregate values in the respective fields.
+1. Group the grid to see the effect
 
 You should define only aggregates that you will use to avoid unnecessary calculations that may be noticeable on large data sets.
 
+If you try to use an aggregate that is not defined, or an aggregate over an unsupported field type, a runtime error will be thrown.
+
 
 >caption Use Aggregates in the Telerik Blazor Grid
 
 ````CSHTML
-@* Enable and use aggregates. To see the effect, group by a column, e.g., Team or "On Vacation" *@
+@* Enable and use aggregates. To see the effect, group by a column - "Team" and then "Active Projects" *@
 
-<TelerikGrid Data=@GridData Groupable="true" Pageable="true" Height="400px">
+<TelerikGrid Data=@GridData Groupable="true" Pageable="true" Height="650px">
     <GridAggregates>
         <GridAggregate Field=@nameof(Employee.Team) Aggregate="@GridAggregateType.Count" />
         <GridAggregate Field=@nameof(Employee.Salary) Aggregate="@GridAggregateType.Max" />
         <GridAggregate Field=@nameof(Employee.Salary) Aggregate="@GridAggregateType.Sum" />
-        <GridAggregate Field=@nameof(Employee.HireDate) Aggregate="@GridAggregateType.Min" />
     </GridAggregates>
     <GridColumns>
         <GridColumn Field=@nameof(Employee.Name) Groupable="false" />
         <GridColumn Field=@nameof(Employee.Team) Title="Team">
-            <GroupFooter>
-                <strong>@((context as GridGroupAggregateResult).Sum)</strong>
-            </GroupFooter>
+            <GroupFooterTemplate>
+                Team Members: <strong>@context.Count</strong>
+            </GroupFooterTemplate>
+            <GroupHeaderTemplate>
+                @context.Value @* the default text you would get without the template *@
+                &nbsp;<span>Team size: @context.Count</span>
+            </GroupHeaderTemplate>
+        </GridColumn>
+        <GridColumn Field=@nameof(Employee.Salary) Title="Salary" Groupable="false">
+            <GroupFooterTemplate>
+                @* you can use a group footer for non-groupable columns as well *@
+                Total montly salary: @context.Sum
+                <br />
+                <span style="color: red;">Top paid employee: @context.Max</span>
+            </GroupFooterTemplate>
+        </GridColumn>
+        <GridColumn Field=@nameof(Employee.ActiveProjects) Title="Active Projects">
+            <GroupHeaderTemplate>
+                @{
+                    <span>Currently active projects: @context.Value &nbsp;</span>
+
+                    //sample of conditional logic in the group header
+                    if ( (int)context.Value > 3) // in a real case, you may want to ensure type safety and add defensive checks
+                    {
+                        <strong style="color: red;">These people work on too many projects</strong>
+                    }
+                }
+            </GroupHeaderTemplate>
         </GridColumn>
-        <GridColumn Field=@nameof(Employee.Salary) Title="Salary" Groupable="false" />
-        <GridColumn Field=@nameof(Employee.HireDate) Title="Hire Date" Groupable="false" />
-        <GridColumn Field=@nameof(Employee.IsOnLeave) Title="On Vacation" />
     </GridColumns>
 </TelerikGrid>
 
@@ -72,7 +101,7 @@ You should define only aggregates that you will use to avoid unnecessary calcula
                 Name = "Employee " + i.ToString(),
                 Team = "Team " + i % 3,
                 Salary = rnd.Next(1000, 5000),
-                IsOnLeave = i % 2 == 0
+                ActiveProjects = i % 4 == 0 ? 2 : 5
             });
         }
     }
@@ -83,12 +112,15 @@ You should define only aggregates that you will use to avoid unnecessary calcula
         public string Name { get; set; }
         public string Team { get; set; }
         public decimal Salary { get; set; }
-        public DateTime HireDate { get; set; }
-        public bool IsOnLeave { get; set; }
+        public int ActiveProjects { get; set; }
     }
 }
 ````
 
+>caption The result of the code snippet above after the grid has been grouped by the `Team` and `Active Projects` columns
+
+![](images/grid-aggregates-overview.png)
+
 
 ## See Also
 

components/grid/grouping.md

@@ -22,6 +22,8 @@ To remove a group setting, click the `[x]` button on its indicator in the group
 
 To prevent grouping by a field, set `Groupable="false"` for on its column. This can be useful for fields with unique values like IDs or names.
 
+You can also use [aggregates]({%slug grid-aggregates%}) for the grouped data.
+
 >caption Enable grouping in Telerik Grid
 
 ````CSHTML
@@ -72,5 +74,6 @@ Drag the column header of the "Team" and/or "On Vacation" column to the group pa
 ## See Also
 
   * [Live Demo: Grid Grouping](https://demos.telerik.com/blazor-ui/grid/grouping)
+  * [Grid Aggregates]({%slug grid-aggregates%})
 
 

components/grid/images/grid-aggregates-overview.png

@@ -15,6 +15,9 @@ The Grid component can use templates for:
 * [rows](#row-template)
 * [editing of a field](#edit-template)
 * [column header](#header-template)
+* [column group footer](#column-group-footer)
+* [group header](#group-header)
+
 
 Like other Blazor content, they can receive a `context` argument that is the type of the model. To use templates, you must bind the grid to a named model.
 
@@ -304,6 +307,14 @@ Bound columns render the name of the field or their `Title` in their header. Thr
 
 >note Header Templates are not available for the `GridCheckboxColumn` and the `GridCommandColumn`.
 
+## Column Group Footer
+
+When the grid is grouped, the columns can display a footer with information about the column data and some custom text/logic. The template is strongly typed and exposes the available aggregates values. For more information and examples, see the [Aggregates]({%slug grid-aggregates%}) article.
+
+## Group Header
+
+When the grid is grouped, the top row above the group provides information about the current group value by default. You can use this template to add custom content there in addition to the current value. For more information and examples, see the [Aggregates]({%slug grid-aggregates%}) article.
+
 ## See Also
 
  * [Live Demo: Grid Templates](https://demos.telerik.com/blazor-ui/grid/templates)