diff --git a/blazor/datagrid/column-headers.md b/blazor/datagrid/column-headers.md index 6541ddbc54..2f019e686c 100644 --- a/blazor/datagrid/column-headers.md +++ b/blazor/datagrid/column-headers.md @@ -1,7 +1,7 @@ --- layout: post title: Column Header in Blazor DataGrid Component | Syncfusion -description: Checkout and learn here all about column header in the Syncfusion Blazor DataGrid component and much more details. +description: Learn how to customize column headers in Syncfusion Blazor DataGrid, including text, templates, alignment, styles, tooltips, and orientation. platform: Blazor control: DataGrid documentation: ug @@ -9,13 +9,12 @@ documentation: ug # Headers in Blazor DataGrid -The Syncfusion® Blazor DataGrid provides a comprehensive set of options to customize and manage headers efficiently. Headers play a crucial role in organizing and presenting data effectively in the Grid. +The Syncfusion® Blazor DataGrid provides options to customize and manage headers for better data organization and presentation. ## Header text -By default, the header text of a column in Syncfusion® Blazor DataGrid is displayed from the column's [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) value. However, you can easily override the default header title and provide a custom header text for the column using the [HeaderText](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderText) property. - -To enable the `HeaderText` property, you simply need to define it in the **GridColumn**. The following example demonstrates how to enable header text for a Grid column: +The Syncfusion® Blazor DataGrid displays the header text of a column from its [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) value by default. +To override this and provide a custom header title, define the [HeaderText](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderText) property in the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html). {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -87,20 +86,16 @@ To enable the `HeaderText` property, you simply need to define it in the **GridC {% previewsample "https://blazorplayground.syncfusion.com/embed/LNrUMtACJAAfwAum?appbar=false&editor=false&result=true&errorlist=false&theme=bootstrap5" %} ->* The `HeaderText` property is optional, and if it is not defined, then the corresponding column's field value is set as header text for that column. ->* You can also use the [HeaderTemplate](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderTemplate) of the `GridColumn` to apply custom HTML content to the header cell. +>* The `HeaderText` property is optional. If it is not defined, the column’s `Field` value is used as the header text. +>* To apply custom HTML content to the header cell, use the [HeaderTemplate](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderTemplate) property of the `GridColumn`. ## Header template -The [HeaderTemplate](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderTemplate) of the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html) used to customize the header element of a Grid column. With this property, you can render custom HTML elements or Blazor components to the header element. This feature allows you to add more functionality to the header, such as sorting or filtering. - -To know about **Header Template** in Grid, you can check this video. +The Syncfusion® Blazor DataGrid allows customizing the header element of a column using the [HeaderTemplate](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderTemplate) property of the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html). This property enables rendering custom HTML elements or Blazor components in the header cell, allowing additional functionality such as icons, dropdowns, or switches. {% youtube "youtube:https://www.youtube.com/watch?v=9YF9HnFY5Ew"%} -In this demo, the custom element is rendered for both **EmployeeID** and **OrderDate** column headers. - {% tabs %} {% highlight razor tabtitle="Index.razor" %} @using Syncfusion.Blazor.Grids @@ -229,14 +224,14 @@ public class OrderDetails {% previewsample "https://blazorplayground.syncfusion.com/embed/LXVJshXLfRNuKUbF?appbar=false&editor=false&result=true&errorlist=false&theme=bootstrap5" %} ->* The `HeaderTemplate` property is only applicable to Grid columns that have a header element. ->* You can use any HTML or Blazor component in the header template to add additional functionality to the header element. +>* The `HeaderTemplate` property is applicable only to columns that have a header element. +> * Any HTML or Blazor component can be used in the header template to add additional functionality. ## Stacked header -In DataGrid, you can group multiple levels of column headers by stacking the Grid columns. This feature allows you to organize the Grid columns in a more structured and understandable way.This can be achieved by nesting the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn) directive within another `GridColumn` directive.You can define the `HeaderText` property of each sub-header column to set the text for that sub-header. +The Syncfusion® Blazor DataGrid allows grouping multiple levels of column headers by stacking columns. This feature organizes columns in a structured way and improves readability. -In the following sample, the columns **Order Date**, and **Freight** are grouped under **Order Details** and the columns **Shipped Date**, and **Ship Country** are grouped under **Shipped Details**: +To achieve this, nest the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn) directive within another `GridColumn` directive. Use the [HeaderText](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderText) property for each sub-header column to set its text. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -344,16 +339,16 @@ public class OrderDetails {% previewsample "https://blazorplayground.syncfusion.com/embed/LNhJMLtKrNbNTfwi?appbar=false&editor=false&result=true&errorlist=false&theme=bootstrap5" %} -## Align the text of header text +## Header text alignment + +The Syncfusion® Blazor DataGrid allows horizontally aligning the text in column headers using the [HeaderTextAlign](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderTextAlign) property of the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html). By default, the text is aligned to the **left**. -You can horizontally align the text in column headers of the Grid using the [HeaderTextAlign](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderTextAlign) property of the `GridColumn`. By default, the text is aligned to the left, but you can change the alignment by setting the value of the `HeaderTextAlign` property to one of the following options: +The alignment can be changed by setting `HeaderTextAlign` to one of the following options: * **Left**: Aligns the text to the left (default). * **Center**: Aligns the text to the center. * **Right**: Aligns the text to the right. -* **Justify**: Header text is justified. - -Here is an example of using the `HeaderTextAlign` property to align the text of a Grid column header: +* **Justify**: Justifies the header text. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -423,26 +418,25 @@ Here is an example of using the `HeaderTextAlign` property to align the text of {% previewsample "https://blazorplayground.syncfusion.com/embed/BNLqWMjsrtUyIcLO?appbar=false&editor=false&result=true&errorlist=false&theme=bootstrap5" %} ->* The `HeaderTextAlign` property only changes the alignment of the text in the column header, and not the content of the column. If you want to align both the column header and content, you can use the [TextAlign](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_TextAlign) property. ->* You can also use the `HeaderTextAlign` property with the stacked header feature in Grid. The property will align the header text in the sub-headers as well. +>* The `HeaderTextAlign` property only changes the alignment of the text in the column header, not the content of the column. To align both the header and the column content, use the [TextAlign](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_TextAlign) property. -## Autowrap the header text +> * The `HeaderTextAlign` property can also be used with stacked headers. It aligns the header text in sub-headers as well. -The autowrap allows the cell content of the Grid to wrap to the next line when it exceeds the boundary of the specified cell width. The cell content wrapping works based on the position of white space between words. To support the Autowrap functionality in Grid, you should set the appropriate [Width](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Width) for the columns. The column width defines the maximum width of a column and helps to wrap the content automatically. +## Autowrap the header text -To enable auto wrap, set the [AllowTextWrap](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_AllowTextWrap) property to `true`. You can configure the auto wrap mode by setting the [TextWrapSettings.WrapMode](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_TextWrapSettings) property. +The Syncfusion® Blazor DataGrid supports wrapping header text when it exceeds the column width. Enable this feature by setting the [AllowTextWrap](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_AllowTextWrap) property to **true**. Configure the wrap mode using the [TextWrapSettings.WrapMode](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_TextWrapSettings) property. -Grid provides the below three options for configuring: +Specify appropriate column widths using the [Width](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Width) property to ensure proper wrapping. -* **Both**: This is the default value for wrapMode. With this option, both the Grid header text and content is wrapped. -* **Header**: With this option, only the Grid header text is wrapped. -* **Content**: With this option, only the Grid content is wrapped. +Wrap modes determine whether header text, content, or both are wrapped: -> * If a column width is not specified, then the Autowrap of columns will be adjusted with respect to the Grid's width. -> * If a column's header text contains no white space, the text may not be wrapped. -> * If the content of a cell contains HTML tags, the Autowrap functionality may not work as expected. In such cases, you can use the [HeaderTemplate](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderTemplate) and [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) properties of the column to customize the appearance of the header and cell content. +* **Both**: Wraps both header text and content (default). +* **Header**: Wraps only header text. +* **Content**: Wraps only content. -The following example demonstrates how to dynamically change the auto-wrap of the header text based on DropDown change: +> * If column width is not specified, wrapping adjusts based on the grid’s width. +> * Header text without white space does not wrap. +> * For cells containing HTML tags, use [HeaderTemplate](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderTemplate) and [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) properties for customization. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -536,11 +530,11 @@ public class InventoryData ## Change the height of header -Changing the height of the header can be useful in cases where the default height is not sufficient to display the header content cell. For example, if you have a header with a lot of text or if you want to add an image to the header, you may need to increase the height of the header to accommodate the content.This can be easily achieved by changing the height of the header using CSS or by dynamically adjusting the height using a methods. +Changing the header height is useful when the default size is not sufficient to display the header content. Headers with lengthy text or images require additional height to ensure proper display. This can be achieved by applying CSS or adjusting the height dynamically using methods. **Using css** -You can use CSS to override the default height of the **.e-grid .e-headercell** class to change the height of the header. Here is an example code snippet: +Override the default height of the **.e-grid .e-headercell** class to set a custom header height: ```css .e-grid .e-headercell { @@ -550,31 +544,52 @@ You can use CSS to override the default height of the **.e-grid .e-headercell** ## Change header text dynamically -The Syncfusion® Blazor DataGrid provides a way to modify the header text of a corresponding column in real-time based on events or other events. This feature can be useful in various scenarios, such as displaying a custom header text for a specific column or updating the header text dynamically based on input. By allowing for dynamic changes to the header text, the Grid provides a more flexible and customizable experience. +The Syncfusion® Blazor DataGrid allows modifying the header text of a column in real time. This can be achieved in two ways: + +* **Using event**: The [HeaderCellInfo](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_HeaderCellInfo) event triggers for each header cell during rendering. It provides access to the header cell element, allowing customization of the header text dynamically. +* **Using methods**: The Grid includes methods such as [GetColumnByFieldAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_GetColumnByFieldAsync_System_String_) and [GetColumnByUidAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_GetColumnByUidAsync_System_String_) to retrieve column objects and update their [HeaderText](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderText) property. After updating, call [RefreshHeaderAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_RefreshHeaderAsync) to apply changes. + +> * When the header text is changed dynamically, the Grid does not update automatically. Call the `RefreshHeaderAsync` method to refresh the Grid and apply the updated header text. + +### Using Event + +The [HeaderCellInfo](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_HeaderCellInfo) event is triggered for each header cell during rendering. This event can be used to customize the header text dynamically. + +**Event Arguments** + +The event uses the [HeaderCellInfoEventArgs](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.HeaderCellInfoEventArgs.html) class, which includes: + +| Property | Type | Description | +|----------|--------|---------------------------------------------| +| cell | object | Represents the header cell being modified. | +| node | object | Represents the DOM element of the header cell.| + -**Using Event** +After updating the header text, call the `RefreshHeaderAsync` method to apply changes. -To modify the header text of a corresponding column dynamically, you can use the [HeaderCellInfo](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_HeaderCellInfo) event provided by the Grid. This event is triggered for each header cell element rendered in the Grid. +### Using method -When the `HeaderCellInfo` event is triggered, it provides a **HeaderCellInfoEventArgs** object as a parameter. This object contains the following properties: +The Syncfusion® Blazor DataGrid provides methods to change the header text dynamically. These methods allow retrieving column objects and updating their [HeaderText](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderText) property. After updating, call the `RefreshHeaderAsync` method to apply changes. -* **cell**: Defines the header cell that is being modified. -* **node**: Defines the DOM element of the header cell that is being modified. +**Get Column by Field** -You can use these properties to access and modify the header text of the corresponding column. Once the header text is modified, you can refresh the Grid to reflect the changes by calling the [RefreshHeaderAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_RefreshHeaderAsync) method of the Grid. +The [GetColumnByFieldAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_GetColumnByFieldAsync_System_String_) method is used to retrieve a column object based on its field name. After retrieving the column, modify the `HeaderText` property of the column object and refresh the header. -**Using method** -The Grid provides several methods that allow you to change the column header text dynamically. Here are some of the methods you can use: +| Parameter | Type | Description | +|------------|--------|--------------------------------------------------------------| +| fieldName | string | Specifies the field name of the column to update header text.| -1. [GetColumnByFieldAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_GetColumnByFieldAsync_System_String_): This method takes a field name as a parameter and returns the entire column object that corresponds to that field name, including properties such as headerText, width, and alignment. You can use this method to modify any aspect of the column. +**Get Column by Uid** -2. [GetColumnByUidAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_GetColumnByUidAsync_System_String_): Retrieves the column object based on its unique identifier. You can modify the `HeaderText` property of the column object to change the header text. - -> * When you change the header text dynamically, you need to **refresh** the Grid to reflect the changes by calling the [RefreshHeaderAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_RefreshHeaderAsync) method. -> * The unique identifier is automatically generated by the Grid and may change whenever the Grid is refreshed or updated. +The [GetColumnByUidAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_GetColumnByUidAsync_System_String_) method is used to retrieve a column object based on its unique identifier. After retrieving the column, update its `HeaderText` property and refresh the header. -Here is an example of how to change the header text of a column using the `GetColumnByFieldAsync` method: + +| Parameter | Type | Description | +|-----------|--------|--------------------------------------------------------------| +| uid | string | Specifies the unique identifier of the column to update header text.| + +> * The unique identifier is automatically generated by the Grid and changes whenever the Grid is refreshed or updated. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -702,7 +717,7 @@ public class OrderDetails **Changing the header text of all columns** -If you want to change the header text of all columns in the Grid, you can loop through the Columns collection of the Grid and set the [HeaderText](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderText) property for each column. Here is an example: +To change the header text of all columns in the Grid, loop through the Columns collection and set the [HeaderText](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderText) property for each column. When the header text is changed dynamically, call the `RefreshHeaderAsync` method to refresh the Grid and reflect the updated headers. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -790,13 +805,13 @@ public class OrderDetails ## Change the orientation of header text -By default, the text in the column headers of the Syncfusion® Blazor DataGrid is oriented horizontally. However, in some cases, you may want to change the orientation of the header text to vertical, diagonal, or at a custom angle. This can be achieved by adding a custom CSS class to the column header cell using the [CustomAttributes](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_CustomAttributes) property of the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html). +By default, the text in the column headers of the Syncfusion® Blazor DataGrid is displayed **horizontally**. To change the orientation to **vertical**, **diagonal**, or a **custom angle**, apply a custom CSS class to the header cell using the [CustomAttributes](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_CustomAttributes) property of [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html). -Follow the below steps to change the orientation of the header text in Grid: +**Steps to change header text orientation:** -**Step 1**: **Create a CSS class with orientation style for Grid header cell** +**1. Create a CSS class with rotation style** -To `rotate` the header text, you can create a CSS class with the `transform` property that rotates the header text 90 degrees. This class will be added to the header cell using the `CustomAttributes` property. +Define a CSS class using the **transform** property to rotate the header text: ```css .e-grid .e-columnheader .e-headercell.orientation .e-headercelldiv { @@ -804,19 +819,19 @@ To `rotate` the header text, you can create a CSS class with the `transform` pro } ``` -**Step 2**: **Add the custom CSS class to the Grid column** +**2. Apply the CSS class to the column** -Once you have created the CSS class, you can add it to the particular column by using the `CustomAttributes` property. This property allows you to add any custom attribute to the GridColumn. - -For example, to add the orientation class to the CustomerID column, you can use the following code: +Use the `CustomAttributes` property to add the class to the desired column: ```cshtml - + + ``` -**Step 3**: **Resize the header cell height** +**3. Adjust header cell height** -After adding the custom CSS class to a column, you need to resize the header cell height so that the rotated header text is fully visible. You can do this by using the following code: +Ensure the rotated text is visible by resizing the header cell height: ```cshtml function setHeaderHeight(args) { @@ -828,8 +843,6 @@ function setHeaderHeight(args) { } ``` -This is demonstrated in the following sample: - {% tabs %} {% highlight razor tabtitle="Index.razor" %} @using Syncfusion.Blazor.Grids @@ -919,16 +932,13 @@ This is demonstrated in the following sample: ## Custom tooltip for header -Custom tooltips for headers provide additional information when hovering over a column header in the Grid. This can be useful in situations where there is not enough space to display all of the information related to a column, or when there is additional context that may be helpful. +Custom tooltips for headers provide additional information when hovering over a column header in the Grid. This is useful when there is limited space to display details or when extra context is required. -To enable custom tooltips for headers in the Grid, you can use the [HeaderTemplate](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderTemplate) feature by rendering the [SfTooltip](https://blazor.syncfusion.com/documentation/tooltip/getting-started) within the template. - -Here's an example of how to use the `HeaderTemplate` to add a custom tooltip to a header cell: +To add custom tooltips for headers, use the [HeaderTemplate](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderTemplate) property and render the [SfTooltip](https://blazor.syncfusion.com/documentation/tooltip/getting-started) component inside the template. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @using Syncfusion.Blazor.Grids -@using Syncfusion.Blazor.Popups @@ -1041,15 +1051,23 @@ public class OrderDetails {% endhighlight %} {% endtabs %} +> The Syncfusion Blazor DataGrid component includes a built-in feature to customize tooltip content for both header cells and content cells. For more information, refer to the documentation [here](https://blazor.syncfusion.com/documentation/datagrid/cell#show-tooltip). + {% previewsample "https://blazorplayground.syncfusion.com/embed/LtrJirtAJDjvaNlx?appbar=false&editor=false&result=true&errorlist=false&theme=bootstrap5" %} ## Customize header text styles -Customizing the Syncfusion® Blazor DataGrid header styles allows you to modify the appearance of the column header in the Grid to meet your design requirements. You can customize the font, background color, and other styles of the header cells. To customize the header styles in the Grid, you can use CSS and CustomAttributes property of the GridColumn. +Customizing the Syncfusion® Blazor DataGrid header styles allows modifying the appearance of column headers to match design requirements. Styles such as **font**, **background color**, and **text color** can be applied using the following approaches: + +* **Using CSS** - Apply styles globally or to specific columns by defining CSS rules. + +* **Using property** - Assign a custom CSS class to individual columns using the [CustomAttributes](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_CustomAttributes) property of [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html). + +* **Using event** - Handle the [HeaderCellInfo](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_HeaderCellInfo) event to apply styles dynamically when header cells are rendered. ### Using CSS -You can apply styles to the header cells using CSS selectors. The Grid provides a class name for each header cell element, which you can use to apply styles to that specific header cell. The **.e-headercell** class can be used to change the background color and text color of the column header. +Apply styles to header cells by defining CSS rules. The **.e-headercell** class targets all header cells and can be used to change properties like **background color** and **text color**. ```CSS .e-grid .e-headercell { @@ -1057,7 +1075,8 @@ You can apply styles to the header cells using CSS selectors. The Grid provides color:rgb(3, 2, 2); } ``` -Here's an example that demonstrates how to customize the appearance of a specific column header in the Grid using **className**. + +To style a specific column header, assign a custom class to that column and define styles for that class in CSS. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -1133,11 +1152,9 @@ Here's an example that demonstrates how to customize the appearance of a specifi ### Using property -You can customize the appearance of the column headers in Grid using the [CustomAttributes](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_CustomAttributes) property of the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html). The `CustomAttributes` property takes an object with the name-value pair to customize the CSS properties for Grid header cells. You can also set multiple CSS properties to the custom class using the customAttributes property. +The [CustomAttributes](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_CustomAttributes) property of [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html) allows assigning a custom CSS class to specific column headers for styling. This approach is useful for applying unique styles without affecting other headers. -To customize the header of a column, you can follow the steps below: - -Step 1: Define a CSS class that specifies the styles you want to apply to the header cell of the column. For example, to change the background color and text color of the header cell, define a CSS class like this: +**Step 1:** Define a CSS class with the desired styles for the header cell. ```CSS .e-grid .e-headercell.customcss { @@ -1147,14 +1164,15 @@ Step 1: Define a CSS class that specifies the styles you want to apply to the he ``` -Step 2: Set the **CustomAttributes** property of the desired column to an object that contains the CSS class **customcss**. This CSS class will be applied to the header cell of the specified column in the Grid. +**Step 2:** Assign the CSS class to the column using the `CustomAttributes` property. ```cshtml - + + ``` -The following example demonstrates how to customize the appearance of the **OrderID** and **Freight** columns using custom attributes: - {% tabs %} {% highlight razor tabtitle="Index.razor" %} @using Syncfusion.Blazor.Grids @@ -1228,9 +1246,7 @@ public class OrderDetails ### Using event -To customize the appearance of the Grid header, you can handle the [HeaderCellInfo](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_HeaderCellInfo) event of the Grid. This event is triggered when each header cell is rendered in the Grid, and provides an object that contains information about the header cell. You can use this object to modify the styles of the header column. - -The following example demonstrates how to add a `HeaderCellInfo` event handler to the Grid. In the event handler, checked whether the current header column is **Order Date** field and then applied the appropriate CSS class to the cell based on its value: +The [HeaderCellInfo](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_HeaderCellInfo) event is triggered when each header cell is rendered in the Grid. This event provides information about the header cell and allows applying custom styles dynamically based on column properties or conditions. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -1319,11 +1335,7 @@ public class OrderDetails ## How to refresh header -The refresh header feature in the Syncfusion® Blazor DataGrid allows you to update the header section of the Grid whenever changes are made to the Grid's columns. This feature is useful when you want to reflect changes in the header immediately, such as modifying the column header text, width, or alignment. - -To use the refresh header feature, you can call the [RefreshHeaderAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_RefreshHeaderAsync) method of the Grid. This method updates the Grid header with the latest changes made to the columns. - -The following example demonstrates how to use the `RefreshHeaderAsync` method to update the Grid header: +The refresh header feature updates the header section of the Syncfusion® Blazor DataGrid when changes are made to column properties such as header text, width, or alignment. The [RefreshHeaderAsync](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_RefreshHeaderAsync) method of the Grid is used to apply these changes immediately. {% tabs %} {% highlight razor tabtitle="Index.razor" %} diff --git a/blazor/datagrid/column-rendering.md b/blazor/datagrid/column-rendering.md index 693c2207c0..86a217f447 100644 --- a/blazor/datagrid/column-rendering.md +++ b/blazor/datagrid/column-rendering.md @@ -9,23 +9,17 @@ documentation: ug # Column Rendering in Blazor DataGrid -In Syncfusion® Blazor DataGrid, column rendering provides you with the ability to finely control how data is presented. This allows you to manually define columns, automatically generate them, and dynamically customize data presentation. With column rendering, you can ensure that your data is displayed exactly as needed, offering a wide range of possibilities for organizing and showcasing information within the Grid. +The Syncfusion® Blazor DataGrid provides flexible options to control how columns are rendered. Columns can be manually defined, automatically generated, or customized dynamically to ensure data is displayed as required. -The column definitions are used as the [DataSource](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_DataSource) schema in the Grid. The Grid operations such as sorting, filtering and grouping etc. are performed based on column definitions. The [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) property of Grid column is necessary to map the `DataSource` values in the Grid columns. +Column definitions act as the [DataSource](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_DataSource) schema for the Grid. Operations such as sorting, filtering, and grouping are performed based on these definitions. The [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) property is essential for mapping `DataSource` values to Grid columns. -> If the column `Field` is not specified in the `DataSource`, the column values will be empty. -> If the `Field` name contains **dot** operator, it is considered as complex binding. -> It is must to define the `Field` property for a Template column, to perform CRUD or data Operations such as filtering, searching etc. +> * If the column `Field` is not present in the `DataSource`, the column will display **empty** values. +> * If the `Field` name contains a **dot** operator, it is treated as complex binding. +> * The `Field` property must be defined for a [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) column to enable CRUD and data operations such as filtering and searching. ## Define columns manually -To define columns manually in Syncfusion® Blazor DataGrid, you can use the `GridColumn` to define the columns and represent each column with its respective properties such as [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field), [HeaderText](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderText), [Type](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Type), and [Width](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Width) set accordingly. This allows you to customize the column's behavior and appearance based on the requirements. - -> 1. If the column [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) is not specified in the dataSource, the column values will be empty. -> 2. If the [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) name contains “dot” operator, it is considered as complex binding. -> 3. It is must to define the [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) property for a [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) column, to perform CRUD or Data Operations such as filtering, searching etc. - -Here's an example code snippet that demonstrates how to define columns manually in the Grid: +To define columns manually in Syncfusion® Blazor DataGrid, use [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html) to specify each column and configure properties such as [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field), [HeaderText](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderText), [Type](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Type), and [Width](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Width). This approach provides full control over column behavior and appearance. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -98,9 +92,7 @@ Here's an example code snippet that demonstrates how to define columns manually ## Auto generated columns -The Syncfusion® Blazor DataGrid automatically generates columns when the [Columns](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.ColumnModel.html#Syncfusion_Blazor_Grids_ColumnModel_Columns) declaration is empty or undefined while initializing the Grid. All the columns in the **DataSource** are bound as Grid columns. - -You can use the following code snippet to enable auto-generated columns in the Grid: +The Syncfusion® Blazor DataGrid automatically generates columns when the `Columns` collection is not defined during Grid initialization. All properties in the [DataSource](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_DataSource) are rendered as Grid columns. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -162,20 +154,16 @@ You can use the following code snippet to enable auto-generated columns in the G {% previewsample "https://blazorplayground.syncfusion.com/embed/rjBKWiXngmWUgDyz?appbar=false&editor=false&result=true&errorlist=false&theme=bootstrap5" %} ->* When the columns are auto-generated, the column [Type](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Type) is determined from the first record of the [DataSource](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_DataSource). ->* If you have a large dataset, auto-generating columns can result in performance issues. In this case, it is recommended to specify the columns manually in the columns property during initialization or else use column virtualization feature by setting [EnableColumnVirtualization](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_EnableColumnVirtualization) property value as **true**. - -To know about how to **Customize Auto generated columns using Data Annotation** in Grid, you can check this video. +> * When columns are auto-generated, the column [Type](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Type) is determined from the first record of the `DataSource`. +> * For large datasets, auto-generating columns can impact performance. In such cases, it is recommended to define columns manually or enable column virtualization by setting [EnableColumnVirtualization](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_EnableColumnVirtualization) to **true**. {% youtube "youtube:https://www.youtube.com/watch?v=f7OIzUM0e7Y"%} -### Set IsPrimaryKey for auto generated columns when editing is enabled - -When editing is enabled in the Grid, you may need to set a primary key for auto-generated columns to uniquely identify each row for operations such as updating or deleting data. This can be achieved using the [IsPrimaryKey](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_IsPrimaryKey) property of the column object by using the [OnDataBound](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_OnDataBound) event. +### Configure primary key for auto-generated columns -By setting `IsPrimaryKey` to **true** for an auto-generated column in the Grid, you can specify it as the primary key column, which uniquely identifies each row when editing is enabled. +When editing is enabled in the Grid, a primary key must be set for auto-generated columns to uniquely identify each row for operations such as updating or deleting data. This can be achieved by using the [IsPrimaryKey](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_IsPrimaryKey) property of the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html) object in the [OnDataBound](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_OnDataBound) event. -Here is an example code snippet that shows how to set a primary key for an auto-generated column when editing is enabled: +Setting `IsPrimaryKey` to **true** for an auto-generated column ensures that the Grid can identify rows uniquely when editing is enabled. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -246,13 +234,9 @@ Here is an example code snippet that shows how to set a primary key for an auto- {% previewsample "https://blazorplayground.syncfusion.com/embed/BtLgsstnKwBBNbFo?appbar=false&editor=false&result=true&errorlist=false&theme=bootstrap5" %} -### Set column options to auto generated columns - -To configure column options such as [Type](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Type), [Format](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Format) and [Width](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Width) for auto-generated columns in Syncfusion® Grid, you can use the [OnDataBound](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_OnDataBound) event of the Grid. This event is triggered after the data has been bound to the Grid. By handling this event, you can specify the desired column options for the auto-generated columns. +### Configure column options for auto-generated columns -Here's an example of how you can set column options for auto-generated columns using the `OnDataBound` event: - -In the below example, `Width` is set for **OrderID** column, **date** `Type` is set for **OrderDate** column and `Format` is set for **Freight** and **OrderDate** column. +Column options such as [Type](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Type), [Format](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Format) and [Width](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Width) can be applied to auto-generated columns using the [OnDataBound](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_OnDataBound) event. This event is triggered after data binding, allowing customization of column properties dynamically. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -342,9 +326,7 @@ In the below example, `Width` is set for **OrderID** column, **date** `Type` is ## Dynamic column generation -The Syncfusion® Blazor DataGrid allows you to dynamically generate columns at runtime, based on the data provided. This feature is useful when you need to display data with varying columns based on user requirements or dynamic data sources. - -You can refer the following code example to achieve this: +The Syncfusion® Blazor DataGrid supports generating columns dynamically at runtime based on the data structure. This approach is useful when the column set changes depending on the data source or when working with flexible models. Columns can be created using reflection or dynamic objects in scenarios where the schema is not fixed. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -417,9 +399,7 @@ You can refer the following code example to achieve this: ### Dynamic column binding using ExpandoObject -It is possible to build a column dynamically without knowing the model type during compile time. This can be achieved by binding data to the Grid as a list of `ExpandoObject`. - -In the following sample, columns are built dynamically using the `ExpandoObject`: +Columns can be generated dynamically at runtime by binding data as a list of [ExpandoObject](https://blazor.syncfusion.com/documentation/datagrid/data-binding/local-data#expandoobject-binding). This approach is useful when working with completely dynamic data structures where column names and values are determined during execution. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -476,15 +456,16 @@ In the following sample, columns are built dynamically using the `ExpandoObject` ## Complex data generation -The Syncfusion® Blazor DataGrid allows you to achieve complex data binding by using the dot (.) operator in the column.field. This feature is particularly useful when dealing with nested or complex data structures. +The Syncfusion® Blazor DataGrid supports complex data binding using the **dot (.)** operator in the [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) property. This feature is useful for displaying nested or hierarchical data structures. ### Using local data -To enable complex data binding in the Grid using local data, use the dot (.) operator in the `Field` property of the column. Here is an example of how to achieve complex data binding using local data: +To bind local data to the Grid using the [DataSource](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_DataSource) property, use the **dot (.)** operator in the [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) property of the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html). -In the below example, we have bound the nested **Employee** object’s **FirstName** and **LastName** properties using the dot (.) operator. +This approach is helpful for binding nested properties like **Employee.FirstName** and **Employee.LastName** from a nested **Employee** object. + +> The **nameof** operator can also be used for complex columns instead of assigning static text for the `Field` property: -> You can also use the **nameof** for complex columns instead of assigning static text for the `Field` property. > ```cshtml > > ``` @@ -539,9 +520,9 @@ In the below example, we have bound the nested **Employee** object’s **FirstNa ### Using remote data -To enable complex data binding in the Grid using remote data, add the [Expand](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Data.Query.html#Syncfusion_Blazor_Data_Query_Expand_System_Collections_Generic_List_System_String__) query to the [Query](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_Query) property of the Grid, to eager load the complex data. Here is an example of how to achieve complex data binding using remote data: +When using remote data, configure data operations through [SfDataManager](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Data.SfDataManager.html), which handles data retrieval, paging, sorting, and other operations from the remote service. -In the below example, we have used the `Expand` query to load the nested Employee object's **City** property using the dot (.) operator: +Complex data binding can be enabled by adding the [Expand](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Data.Query.html#Syncfusion_Blazor_Data_Query_Expand_System_Collections_Generic_List_System_String__) query to the [Query](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_Query) property of the Grid to eager load nested data. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -582,7 +563,9 @@ In the below example, we have used the `Expand` query to load the nested Employe ### Complex data generation using ExpandoObject -Before proceeding this, learn about [ExpandoObject Binding](https://blazor.syncfusion.com/documentation/datagrid/data-binding/local-data#expandoobject-binding). You can achieve ExpandoObject complex data binding in the Grid by using the dot(.) operator in the column.field. In the following examples, `CustomerID.Name` and `ShipCountry.Country` are complex data. +[ExpandoObject](https://blazor.syncfusion.com/documentation/datagrid/data-binding/data-binding#expandoobject-binding) is used when properties need to be added dynamically at runtime. This is suitable for scenarios where the data structure is not fixed. + +Complex data binding can be achieved by using the **dot (.)** operator in the [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) property when working with ExpandoObject. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -629,13 +612,15 @@ Before proceeding this, learn about [ExpandoObject Binding](https://blazor.syncf {% endhighlight %} {% endtabs %} -> * you can perform the Data operations and CRUD operations for Complex ExpandoObject binding fields too. +> * Data operations and CRUD operations are supported for complex DynamicObject binding fields. {% previewsample "https://blazorplayground.syncfusion.com/embed/VXrgXRVXLFuZSlab?appbar=false&editor=false&result=true&errorlist=false&theme=bootstrap5" %} ### Complex data generation using DynamicObject -Before proceeding this, learn about [DynamicObject Binding](https://blazor.syncfusion.com/documentation/datagrid/data-binding/local-data#dynamicobject-binding). You can achieve DynamicObject complex data binding in the Grid by using the dot(.) operator in the column.field. In the following examples, `CustomerID.Name` and `ShipCountry.Country` are complex data. +[DynamicObject](https://blazor.syncfusion.com/documentation/datagrid/data-binding#dynamicobject-binding) is used when custom logic for property access or dynamic behavior is required. + +Complex data binding can be achieved by using the **dot (.)** operator in the [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) property when working with DynamicObject. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -697,15 +682,15 @@ Before proceeding this, learn about [DynamicObject Binding](https://blazor.syncf {% endhighlight %} {% endtabs %} -> * you can perform the Data operations and CRUD operations for Complex DynamicObject binding fields too. +> * Data operations and CRUD operations can also be performed on complex DynamicObject binding fields. {% previewsample "https://blazorplayground.syncfusion.com/embed/BtBgNdrjLuIpsnpS?appbar=false&editor=false&result=true&errorlist=false&theme=bootstrap5" %} ### How to set complex column as foreign key column -The Syncfusion® Blazor DataGrid provides the ability to use complex columns as foreign key columns. This allows related data from a foreign data source to be displayed based on the value of a complex column. +The Syncfusion® Blazor DataGrid supports using complex columns as foreign key columns. This enables related data from a [ForeignDataSource](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridForeignColumn-1.html#Syncfusion_Blazor_Grids_GridForeignColumn_1_ForeignDataSource) to be displayed based on the value of a complex column. -The following example demonstrates how to set the **Employee.EmployeeID** column as a foreign key column, and display the **FirstName** column from the foreign data source: +In this configuration, the **Employee.EmployeeID** column is set as a foreign key column, and the **FirstName** field from the foreign data source is displayed. {% tabs %} {% highlight razor tabtitle="Index.razor" %} diff --git a/blazor/datagrid/column-template.md b/blazor/datagrid/column-template.md index 256d1e7ad7..0379e58717 100644 --- a/blazor/datagrid/column-template.md +++ b/blazor/datagrid/column-template.md @@ -9,22 +9,20 @@ documentation: ug # Column Template in Blazor DataGrid -Syncfusion® Blazor DataGrid provides a [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) option that allows you to display custom elements in a column instead of the field value. This can be useful when you need to display images, buttons, or other custom content within a column. - -> Before adding column template to the Grid, it is recommended to go through the [template](./templates/#templates) section topic to configure the template. - -To know about **Column Template** in Grid, you can check this video. +The Syncfusion® Blazor DataGrid provides a [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property that allows rendering custom elements in a column instead of the default field value. This feature is useful for displaying images, buttons, or other custom content within a column. {% youtube "youtube:https://www.youtube.com/watch?v=9YF9HnFY5Ew"%} -> When using template columns, they are primarily meant for rendering custom content and may not provide built-in support for Grid actions like sorting, filtering, editing. It is must to define the `Field` property of the column to perform any Grid actions. +> Template columns are primarily intended for rendering custom content and do not provide built-in support for actions such as sorting, filtering, or editing. To enable these actions, it is required to define the [Field](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Field) property for the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html). -## Render image in a column +## Render HTML Elements in a Column -To render an image in a Grid column, you need to define a [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) for the column using the template property.The `Template` property expects an HTML string or a function that returns an HTML string. +The Syncfusion® Blazor DataGrid allows rendering HTML elements inside a column using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This enables embedding custom content such as **images** and **hyperlinks** instead of plain text. -The following example demonstrates how to define a `Template` for the **Employee Image** field that displays an image element.The `Template` property is set to an HTML string that contains an image tag. You have utilized the `src` and `alt` attributes to the image tag: +### Render image in a column + +To display an image in a DataGrid column, define the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property for the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html). The `Template` property allows rendering custom HTML or Blazor components instead of the default field value. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -113,13 +111,11 @@ The following example demonstrates how to define a `Template` for the **Employee ![Render image in a column](./images/render-image-column-template.png) -> The [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) option allows to define any HTML content within a column. - -## Render hyperlink in a column +> The `Template` property allows defining any HTML content or Blazor components within a column, enabling complete customization of cell rendering. -The Syncfusion® Blazor DataGrid provides support for rendering hyperlink columns and performing routing on click using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This feature is useful when displaying data that requires a link to another page or website. +### Render hyperlink in a column -The following example demonstrates, how to render hyperlink column in the Grid using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property of the `GridColumn` tag. To define a `Template` for the column, you can use the `Template` with the `a` tag to create the hyperlink: +The Syncfusion® Blazor DataGrid supports rendering hyperlinks in columns using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This feature is useful for displaying data that links to another page or external resource. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -194,13 +190,11 @@ public class EmployeeDetails ## Render other components in a column -The column template has options to render a custom component in a Syncfusion® Blazor DataGrid column instead of a field value. +The Syncfusion® Blazor DataGrid supports rendering other Syncfusion components inside a column using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This allows embedding interactive elements for advanced customization. ### Render LineChart in a column -The [LineChart](https://blazor.syncfusion.com/documentation/sparkline/getting-started-webapp) of Syncfusion® provides an elegant way to represent and compare data over time. It displays data points connected by straight line segments to visualize trends in data. - -In the following example, we rendered the Sparkline Chart in the Grid column by defining the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property: +The [LineChart](https://blazor.syncfusion.com/documentation/sparkline/getting-started-webapp) provided by Syncfusion® offers an elegant way to represent and compare data over time. It displays data points connected by straight line segments to visualize trends. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -299,13 +293,7 @@ public class EmployeeDetails ### Render DropDownList in a column -To render a custom component in a Syncfusion® Blazor DataGrid column, you need to define a [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) for the column using the column `Template` property. In the following code, we rendered the [DropDownList](https://blazor.syncfusion.com/documentation/dropdown-list/getting-started-with-web-app) in the **Order Status** column by defining the `Template` property. - -```csharp - - - -``` +The Syncfusion® Blazor DataGrid allows rendering a [DropDownList](https://blazor.syncfusion.com/documentation/dropdown-list/getting-started-with-web-app) inside a column using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This feature is commonly used to provide inline selection of predefined values directly within the grid, such as choosing from predefined options for a field. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -395,17 +383,7 @@ public class OrderDetails ### Render Chip in a column -The Syncfusion® Blazor DataGrid provides support for rendering [Chips](https://blazor.syncfusion.com/documentation/chip/getting-started-with-web-app) in a column using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This feature is useful when displaying data that requires a chip to be rendered in a column. - -In the following code, we rendered the Chips in the Grid **First Name** column by defining the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property: - -``` - - - - - -``` +The Syncfusion® Blazor DataGrid supports rendering [Chips](https://blazor.syncfusion.com/documentation/chip/getting-started-with-web-app) inside a column using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This feature is useful for displaying data as visually distinct elements, such as tags or labels, within the grid. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -483,14 +461,7 @@ public class EmployeeDetails ### Render ProgressBar in a column -The Syncfusion® Blazor DataGrid supports rendering the [Progress Bar](https://blazor.syncfusion.com/documentation/progress-bar/getting-started-webapp) within a column using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. Displaying the `Progress Bar` in a Grid column allows users to visually track the progress of tasks or operations associated with specific records. This feature is particularly useful for applications involving processes such as data loading, task completion, or other progressive activities. - -In the following code, the `Progress Bar` render in the Grid **Freight** column by defining the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property: - -``` - - -``` +The Syncfusion® Blazor DataGrid supports rendering a [Progress Bar](https://blazor.syncfusion.com/documentation/progress-bar/getting-started-webapp) inside a column using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This feature is useful for visually tracking progress related to specific records. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -567,15 +538,7 @@ public class OrderDetails ### Render RadioButton in a column -The Syncfusion® Blazor DataGrid supports rendering a [RadioButton](https://blazor.syncfusion.com/documentation/radio-button/getting-started-webapp) within a column using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This feature is particularly useful for displaying selection options such as order statuses, payment methods, or approval choices directly within the Grid. - -In the following example, a `RadioButton` is rendered in the **Order Status** column of the Grid by defining the `Template` property: - -``` - - - -``` +The Syncfusion® Blazor DataGrid supports rendering a [RadioButton](https://blazor.syncfusion.com/documentation/radio-button/getting-started-webapp) inside a column using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This feature is useful for scenarios where a single option must be selected from multiple choices within the grid. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -649,9 +612,9 @@ public class OrderDetails ## Using condition template -The conditional column [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) allows you to display template elements based on specific conditions. +The Syncfusion® Blazor DataGrid supports conditional rendering within a column using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This feature allows displaying template elements based on specific conditions in the data source. -In the following code, checkbox is rendered based on **Discontinued** field value in the datasource. This data can be accessed inside the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) using the implicit named parameter **context**: +The `Template` property provides access to the current row’s data through the implicit **context** parameter, enabling conditional logic for rendering elements such as checkboxes, icons, or status indicators. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -737,11 +700,9 @@ In the following code, checkbox is rendered based on **Discontinued** field valu ### Calculate column value based on other columns in Blazor DataGrid -In the Syncfusion® Blazor DataGrid, it is often necessary to display a value that is not directly available in the underlying data source but is instead derived from existing column values. For example, in financial or inventory applications, users may want to show a total or calculated value such as the sum of two cost fields in a separate column. This can be done using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. +In the Syncfusion® Blazor DataGrid, a column can display values derived from other fields in the same row using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This approach is useful for scenarios where calculated values, such as totals or combined costs, need to be shown without adding extra fields to the data source. -The `Template` allows customizing how a column's content is rendered, and it provides access to the current row's data through the **context** parameter. This makes it possible to define inline expressions or logic that compute values based on other fields in the same row. - -In the example below, a new column called **FinalCost** is created to display the sum of the **ManfCost** and **LabCost** columns. This column does not bind to a field in the model but instead calculates the value dynamically within the template. The **context** is cast to the appropriate model type (Order), and the sum is computed and displayed in a
element. +The `Template` property allows defining inline expressions or logic that compute values dynamically. The **context** parameter provides access to the row data, enabling calculations like summing two fields or applying custom formulas. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -797,9 +758,9 @@ In the example below, a new column called **FinalCost** is created to display th ## How to get the row object by clicking on the template element -The Syncfusion® Blazor DataGrid allows you to retrieve the row object of the selected record when clicking on a [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) element. This feature can be useful when you need to perform custom actions based on the selected record. +The Syncfusion® Blazor DataGrid supports retrieving the row object when a [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) element inside a column is clicked. This feature is useful for performing custom actions such as showing detailed information, triggering workflows, or updating related UI components based on the selected record. -In the following code, the button is rendered in the **Employee Data** column and [OnClick](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Buttons.SfButton.html#Syncfusion_Blazor_Buttons_SfButton_OnClick) event binding is used to call the showDetails method when the template element is clicked and the [RowSelected](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_RowSelected) event of the Grid used to access the selected row object and display it in the dialog popup. +The `Template` property allows rendering interactive elements like buttons inside a column. When these elements are clicked, the associated row data can be accessed using the [RowSelected](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridEvents-1.html#Syncfusion_Blazor_Grids_GridEvents_1_RowSelected) event or by handling the [OnClick](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Buttons.SfButton.html#Syncfusion_Blazor_Buttons_SfButton_OnClick) event of the template element. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -892,11 +853,9 @@ public class EmployeeDetails ## Use custom helper inside the template -The Syncfusion® Blazor DataGrid allows you to use custom helpers inside the `Template` directive of a column. This feature allows you to create complex templates that can incorporate additional helper functions that are not available through the default [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) syntax. - -To use the custom helper function inside a column template, you must first add the function to the template's context. +The Syncfusion® Blazor DataGrid supports using custom helper functions inside the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property of a column. This feature is useful for creating complex templates that require additional logic beyond the default template syntax. -The following example demonstrates how to use a custom helper function inside the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property, using the `Template` element for the Freight column: +Custom helper functions can be defined in the component’s code section and invoked within the template using the **context** parameter. This approach allows implementing dynamic behaviors such as formatting values, applying conditional styles, or rendering custom UI elements based on row data. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -976,11 +935,9 @@ public class OrderDetails ## Dynamically adding template column -The Syncfusion® Blazor DataGrid allows you to dynamically add template columns at runtime. This capability is particularly useful when the structure of the Grid needs to be modified based on individual interactions or other dynamic conditions. - -Dynamically adding template columns involves creating and inserting columns with custom templates after the Grid has been initialized. This approach provides flexibility in presenting data in a highly customizable manner. +The Syncfusion® Blazor DataGrid supports dynamically adding template columns at runtime. This feature is useful when the grid structure needs to change based on interactions or dynamic conditions. -The following example demonstrates how to add template column using external button click. In this example, the **ShipCountry** column with a [DropDownList](https://blazor.syncfusion.com/documentation/dropdown-list/getting-started-with-web-app) is added in column [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template), and an icon is displayed using the [HeaderTemplate](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_HeaderTemplate) for the **ShipCountry** column: +Template columns can be created and inserted after the grid has been initialized, allowing custom elements such as dropdowns, buttons, or icons to be rendered dynamically. This approach provides flexibility for scenarios like adding interactive controls or displaying conditional content without modifying the initial grid configuration. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -1077,9 +1034,9 @@ public class OrderDetails ## Using hyperlink column and performing routing on click -The Column template property can be used to provide routing links inside the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property of the [GridColumn](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html). For routing, [UriHelper](https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/routing?view=aspnetcore-7.0&viewFallbackFrom=aspnetcore-3.0#uri-and-navigation-state-helpers) can be utilized. +The Syncfusion® Blazor DataGrid supports adding routing links inside a column using the [Template](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.GridColumn.html#Syncfusion_Blazor_Grids_GridColumn_Template) property. This feature enables navigation to different pages or routes when interacting with template elements. -This can be achieved by initially defining an anchor tag inside the column template and binding click event to it. In this event, the Grid data **context** is passed on to its function. +Routing can be implemented by defining an **anchor tag** or clickable element inside the column template and handling navigation through the [UriHelper](https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/routing?view=aspnetcore-7.0&viewFallbackFrom=aspnetcore-3.0#uri-and-navigation-state-helpers). The **context** parameter provides access to the current row data, allowing dynamic route generation based on record values. {% tabs %} {% highlight razor tabtitle="Index.razor" %} @@ -1162,9 +1119,9 @@ This can be achieved by initially defining an anchor tag inside the column templ {% endhighlight %} {% endtabs %} -In the above code, the url to be navigated is specified in the Link variable of the Grid data. Based on this, the page is routed to the corresponding url. +In this configuration, the navigation URL is defined in the **Link** field of the Grid data. When the link is clicked, the page is routed to the specified URL. -After that, add new razor page for routing with routing url along with the parameters to be received, and initialize it with the required details. +Next, create a new Razor page with the appropriate routing URL and include any required route parameters. Initialize the page with the necessary details. {% tabs %} {% highlight razor tabtitle="FetchData.razor" %}