diff --git a/blazor-toc.html b/blazor-toc.html index 1087e6f50d..f3fa1769c5 100644 --- a/blazor-toc.html +++ b/blazor-toc.html @@ -1826,6 +1826,9 @@
  • Data Binding +
  • Custom Binding diff --git a/blazor/datagrid/data-annotation.md b/blazor/datagrid/data-annotation.md index 06d469eb04..339284a48e 100644 --- a/blazor/datagrid/data-annotation.md +++ b/blazor/datagrid/data-annotation.md @@ -1,49 +1,51 @@ --- layout: post -title: Data Annotation in Blazor DataGrid Component | Syncfusion -description: Checkout and learn here all about Data Annotation in Syncfusion Blazor DataGrid component and much more. +title: Data Annotation in Blazor DataGrid | Syncfusion +description: Learn all about Data Annotation in Syncfusion Blazor DataGrid and more. platform: Blazor control: DataGrid documentation: ug --- -# Data Annotation in Blazor DataGrid Component +# Data Annotation in Blazor DataGrid -Data Annotations helps us to define rules to the model classes or properties to perform data validation and display suitable messages to end users. +Data Annotations are used to define rules for model classes or properties, allowing validation of data and the display of appropriate messages to end-users. By leveraging Data Annotations, you can ensure that data entered into your application conforms to the expected format and meets specific validation criteria. In Syncfusion's Blazor DataGrid, Data Annotations help map these validation rules to the corresponding Grid column properties. -The Data Annotation can be enabled by referencing the **System.ComponentModel.DataAnnotations** namespace which maps the data annotations to the corresponding DataGrid Column property. +To enable Data Annotations for validation in a Grid, you need to reference the **System.ComponentModel.DataAnnotations** namespace in your Blazor application. Once enabled, the Grid automatically uses the data annotations applied to your model class properties to perform data validation. -The list of data annotation attributes that are supported in DataGrid component are provided below, +The following table lists the data annotation attributes supported in the Grid: | Attribute Name | Properties | Functionality | -|-------|---------|---------| -| Display | Name | Sets the header text for the grid column -| Display | ShortName | Sets a shorter version of the header text for the grid column -| Display | AutoGenerateField | Prevents the column from being auto-generated in the grid. -| Display | AutoGenerateFilter | Sets whether filtering should be disabled for a particular column. -| Display | Description | Sets the tooltip text displayed when hovering over the ellipsis of the column. -| Display | Order | Sets the priority order of the Grid Column -| DisplayFormat | FormatString | Sets the format for displaying data in the column. -| DisplayFormat | ApplyFormatInEditMode | Determines whether the column format should be applied in edit mode -| DisplayFormat | NullDisplayText | Sets the text to be displayed when the value of the property is null -| DisplayFormat | ConvertEmptyStringToNull | Determines whether empty string values should be converted to null in the user interface -| DisplayFormat | NeedsHtmlEncode | Sets whether HTML encoding should be disabled for a particular column. -| ScaffoldColumnAttribute | Scaffold | Sets whether the column is visible in the user interface +|---------------|------------|--------------| +| Display | Name | Sets the header text for the Grid column | +| Display | ShortName | Sets a shorter version of the header text for the Grid column | +| Display | AutoGenerateField | Prevents the column from being auto-generated in the Grid | +| Display | AutoGenerateFilter | Specifies whether filtering should be disabled for the column | +| Display | Description | Sets the tooltip text displayed when hovering over the column ellipsis | +| Display | Order | Defines the display order priority of the Grid column | +| DisplayFormat | FormatString | Sets the format for displaying data in the column | +| DisplayFormat | ApplyFormatInEditMode | Determines whether the format should be applied during edit mode | +| DisplayFormat | NullDisplayText | Sets the text to be displayed when the value of the property is null | +| DisplayFormat | ConvertEmptyStringToNull | Determines whether empty string values should be converted to null in the user interface | +| DisplayFormat | NeedsHtmlEncode | Sets whether HTML encoding should be disabled for a particular column | +| ScaffoldColumnAttribute | Scaffold | Sets whether the column is visible in the user interface | | EditableAttribute | ReadOnly | Sets whether the column allows editing | -| Key | Key | This attribute is used to mark a column as the primary key in the data grid | -| Validations are,

    1. RequiredAttribute
    2. StringLengthAttribute
    3. RangeAttribute
    4. RegularExpressionAttribute
    5. MinLengthAttribute
    6. MaxLengthAttribute
    7. EmailAddressAttribute
    8. CompareAttribute
    | | The data annotation validation attributes are used as `validation rules` in the DataGrid CRUD operations| +| Key | Key | Marks a column as the primary key in the Grid | +| Validation Attributes:

    1. RequiredAttribute
    2. StringLengthAttribute
    3. RangeAttribute
    4. RegularExpressionAttribute
    5. MinLengthAttribute
    6. MaxLengthAttribute
    7. EmailAddressAttribute
    8. CompareAttribute
    | | These validation attributes are used as `validation rules` in Grid CRUD operations | -N> The DataGrid Property takes precedence over Data Annotation. For example, when both the DisplayName Attribute and HeaderText are assigned to a Field in the DataGrid Model class for a specific column, the value of the HeaderText property will be prioritized and displayed in the DataGrid header. +> The Syncfusion Blazor DataGrid property takes precedence over data annotation attributes. For example, when both the DisplayName attribute and `HeaderText` are assigned to a field in the Grid model class for a specific column, the `HeaderText` value will be prioritized and displayed in the Grid header. -The following sample code demonstrates data annotations implemented in the DataGrid component, +The following sample code demonstrates how to use data annotations in the Grid: + +{% tabs %} +{% highlight razor tabtitle="Index.razor" %} -```cshtml @using Syncfusion.Blazor.Grids @using Syncfusion.Blazor.DropDowns @using System.Reflection @using System.ComponentModel.DataAnnotations; - + @@ -117,22 +119,22 @@ The following sample code demonstrates data annotations implemented in the DataG public class Order { - // Sets column as primary key + // Sets column as primary key. [Key] - // Sets column as required and error message to be displayed when empty - [Required(ErrorMessage = "Order ID should not be empty")] - // Sets header text to the column + // Sets column as required and error message to be displayed when empty. + [Required(ErrorMessage = "Order ID should not be empty")] + // Sets header text to the column. [Display(ShortName = "ID")] - public int? OrderID { get; set; } + public int OrderID { get; set; } [Display(Name = "CustomerID", Description ="List of Customers")] - // Sets column as required and error message to be displayed when empty + // Sets column as required and error message to be displayed when empty. [Required(ErrorMessage = "Field should not be empty")] [DisplayFormat(NullDisplayText = "Empty", ConvertEmptyStringToNull = true)] public string? CustomerID { get; set; } - // Sets data type of column as Date + // Sets data type of column as Date. [DataType(DataType.Date)] [Display(Name = "Order Date")] - // Sets column as read only + // Sets column as read only. [Editable(false)] public DateTime? OrderDate { get; set; } [Display(Name = "Freight", AutoGenerateFilter = false)] @@ -142,11 +144,16 @@ The following sample code demonstrates data annotations implemented in the DataG public Status Verified { get; set; } } } -``` -The following image represents data annotations enabled in the DataGrid columns, -![Data Annotation in Blazor DataGrid](./images/blazor-datagrid-data-annotation.png) +{% endhighlight %} +{% endtabs %} + +{% previewsample "https://blazorplayground.syncfusion.com/embed/LthIZotuimdZMRyd?appbar=false&editor=false&result=true&errorlist=false&theme=bootstrap5" %} + +The following image shows how Data Annotations are applied to Grid columns in a Blazor application: + +![Data Annotation in Grid](./images/blazor-datagrid-data-annotation.png) -> Displaying Enum Class Display attribute name in the "Verified" Column, this implementation aims to improve user experience by presenting human-readable text in the grid for Enum values associated with the "Verified" column +> The **Verified** column displays the `Enum` member using the `Display` attribute name, enhancing user experience by rendering a human-readable label instead of the raw enum value. -N> You can refer to our [Blazor DataGrid](https://www.syncfusion.com/blazor-components/blazor-datagrid) feature tour page for its groundbreaking feature representations. You can also explore our [Blazor DataGrid example](https://blazor.syncfusion.com/demos/datagrid/overview?theme=bootstrap5) to understand how to present and manipulate data. \ No newline at end of file +> You can refer to our [Syncfusion Blazor DataGrid](https://www.syncfusion.com/blazor-components/blazor-datagrid) feature tour page for its features. You can also explore our [Syncfusion Blazor DataGrid example](https://blazor.syncfusion.com/demos/datagrid/overview?theme=bootstrap5) to understand how to present and manipulate data. diff --git a/blazor/datagrid/databinding/remote-data.md b/blazor/datagrid/databinding/remote-data.md new file mode 100644 index 0000000000..277c73f8c4 --- /dev/null +++ b/blazor/datagrid/databinding/remote-data.md @@ -0,0 +1,424 @@ +--- +layout: post +title: Remote Data in Blazor DataGrid | Syncfusion +description: Learn all about remote data in Syncfusion Blazor DataGrid and much more. +platform: Blazor +control: DataGrid +documentation: ug +--- + +# Remote Data in Blazor DataGrid + +Remote data binding in the Blazor DataGrid enables you to connect to external services such as OData, Web APIs, or RESTful endpoints to efficiently retrieve and manage data. This approach is especially useful when working with large datasets or when your data resides on a server. + +To enable remote data binding, configure the [DataSource](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Grids.SfGrid-1.html#Syncfusion_Blazor_Grids_SfGrid_1_DataSource) property of the `SfGrid` using the [SfDataManager](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Data.SfDataManager.html), which manages communication between the DataGrid and the remote data service. + +You can configure `SfDataManager` in either of the following ways: + +- Declare `SfDataManager` as a separate component inside the DataGrid. +- Assign an instance of `SfDataManager` directly to the `DataSource` property. + +**Basic configuration** + +The following properties must be configured for remote data binding: + +- **Url**: The endpoint of your remote data source. +- **Adaptor**: Specifies the type of data service. Supported adaptors include: + - ODataAdaptor + - ODataV4Adaptor + - WebApiAdaptor + - UrlAdaptor + - GraphQLAdaptor + +> When using `SfDataManager` for remote data binding, you must explicitly define the `TValue` type for the SfGrid component. +> If no adaptor is specified, `SfDataManager` defaults to using the `ODataAdaptor`. + +## Binding with OData services + +[OData](https://www.odata.org/documentation/odata-version-3-0/) (Open Data Protocol) is a standardized protocol designed to simplify data sharing across disparate systems. It enables querying and updating data via RESTful APIs. The Syncfusion Blazor [SfDataManager](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Data.SfDataManager.html) provides built-in support for consuming OData v3 and v4 services, making it easy to bind remote OData service data to the SfGrid component. + +The SfDataManager communicates with the remote OData service using the `ODataAdaptor` or `ODataV4Adaptor`, depending on the OData protocol version. + +> Use `ODataAdaptor` for OData v3 services and `ODataV4Adaptor` for OData v4 services. +> Ensure that the response format of the OData service aligns with the expected Grid data model. + +The following example demonstrates how to bind an OData service to the DataGrid using `SfDataManager`: + +{% tabs %} +{% highlight razor tabtitle="Index.razor" %} + +@using Syncfusion.Blazor +@using Syncfusion.Blazor.Data +@using Syncfusion.Blazor.Grids + + + + + + + + + + + + +@code{ + public class Order { + public int? OrderID { get; set; } + public string CustomerID { get; set; } + public DateTime? OrderDate { get; set; } + public double? Freight { get; set; } + public string ShipCountry { get; set; } + } +} + +{% endhighlight %} +{% endtabs %} + +## Enable SfDataManager after initial rendering + +You can render the data source in the DataGrid after the initial rendering. This can be achieved by conditionally enabling the [SfDataManager](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Data.SfDataManager.html) component after the DataGrid has been rendered. + +The following example demonstrates how to enable the data manager in the DataGrid on a button click: + +{% tabs %} +{% highlight razor tabtitle="Index.razor" %} + +@using Syncfusion.Blazor +@using Syncfusion.Blazor.Buttons +@using Syncfusion.Blazor.Data +@using Syncfusion.Blazor.Grids + + + + + @if (IsDataManagerEnabled) + { + + } + + + + + + + + +@code{ + public bool IsDataManagerEnabled = false; + + public class Order + { + public int? OrderID { get; set; } + public string CustomerID { get; set; } + public DateTime? OrderDate { get; set; } + public double? Freight { get; set; } + } + + public void Enable() + { + // Enable the data manager rendering. + this.IsDataManagerEnabled = true; + } +} + +{% endhighlight %} +{% endtabs %} + +The following GIF demonstrates dynamically rendering the data manager in the DataGrid: + +![Dynamically Rendering Data Manager in Blazor DataGrid](../images/blazor-datagrid-dynamic-render-data-manager.gif) + +## Sending additional parameters to the server + +To add custom parameters to the data request, use the `AddParams` method of the Query class. Assign the Query object with additional parameters to the DataGrid's [Query](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Data.Query.html) property. + +The following example demonstrates sending additional parameters using the Query property: + +{% tabs %} +{% highlight razor tabtitle="Index.razor" %} + +@using Syncfusion.Blazor +@using Syncfusion.Blazor.Data +@using Syncfusion.Blazor.Grids + + + + + + + + + + + + +@code{ + public string ParamValue = "true"; + public Query GridQuery { get; set; } + + protected override void OnInitialized() { + GridQuery = new Query().AddParams("ej2grid", ParamValue); + } + + public class Order + { + public int? OrderID { get; set; } + public string CustomerID { get; set; } + public DateTime? OrderDate { get; set; } + public double? Freight { get; set; } + } +} + +{% endhighlight %} +{% endtabs %} + +## Authorization and Authentication + +When accessing remote data services, it is common for the server to require authorization to prevent anonymous access. The **SfDataManager** can consume data from protected remote services by providing the appropriate bearer (access) token. You can provide the access token to **SfDataManager** in the following ways: + +- **Using a pre-configured HttpClient:** + Register an `HttpClient` instance with the access token or an authentication message handler before calling `AddSyncfusionBlazor()` in your `Program.cs`. This ensures that **SfDataManager** uses the configured `HttpClient` instead of creating its own, allowing it to access protected services. + +- **Setting the access token in the default headers:** + Inject the configured `HttpClient` into your page and set the access token in the default request headers. For example: + + ```csharp + @inject HttpClient _httpClient + + @code { + protected override async Task OnInitializedAsync() + { + _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {tokenValue}"); + await base.OnInitializedAsync(); + } + } + ``` + +- **Using the Headers property of SfDataManager:** + Set the access token directly in the `Headers` property of **SfDataManager**. For more details, see [Setting custom headers](#setting-custom-headers). + +The method for obtaining the bearer token depends on your authentication provider. For more information on configuring `HttpClient` with authentication in Blazor, refer to the official documentation [here](https://learn.microsoft.com/aspnet/core/blazor/security/webassembly/additional-scenarios?view=aspnetcore-8.0). + +## Setting custom headers + +To add custom headers to the data request, use the [Headers](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.DataManager.html#Syncfusion_Blazor_DataManager_Headers) property of the [SfDataManager](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Data.SfDataManager.html). + +The following example demonstrates adding custom headers to the `SfDataManager` request: + +{% tabs %} +{% highlight razor tabtitle="Index.razor" %} + +@using Syncfusion.Blazor +@using Syncfusion.Blazor.Data +@using Syncfusion.Blazor.Grids + + + + @* Replace xxxx with your actual port number *@ + + + + + + + + + +@code{ + private IDictionary HeaderData = new Dictionary(); + + public class Order + { + public int? OrderID { get; set; } + public string CustomerID { get; set; } + public DateTime? OrderDate { get; set; } + public double? Freight { get; set; } + } +} + +{% endhighlight %} +{% endtabs %} + +![Setting Custom Headers](../images/remote-data-custom-headers.png) + +## Dynamically change query parameter values + +You can dynamically update the DataGrid's [Query](https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Data.Query.html) property at runtime to modify the data retrieved from a remote source. + +The following example demonstrates how to change the query parameter value in response to a button click: + +```razor +@using Syncfusion.Blazor +@using Syncfusion.Blazor.Buttons +@using Syncfusion.Blazor.Data +@using Syncfusion.Blazor.Grids + + + + + + + + + + + + +@code { + public SfGrid GridObj; + private Query QueryData = new Query().Where("CustomerID", "equal", "VINET"); + private Query UpdatedQueryData = new Query().Where("CustomerID", "equal", "HANAR"); + + public class Order + { + public int? OrderID { get; set; } + public string CustomerID { get; set; } + public double? Freight { get; set; } + } + + public void BtnClick() + { + QueryData = UpdatedQueryData; + } +} +``` + +The following GIF illustrates how the DataGrid updates its data when the query parameter is changed dynamically: + +![Changing Query Dynamically in Blazor DataGrid](./images/blazor-datagrid-query-update.gif) + +## Offline mode + +On remote data binding, all Grid actions such as paging, sorting, editing, grouping, filtering, etc, will be processed on server-side. To avoid post back for every action, set the grid to load all data on initialization and make the actions process in client-side. To enable this behavior, use the `Offline` property of DataManager. + +{% tabs %} +{% highlight razor tabtitle="Index.razor"%} + +@using Syncfusion.Blazor.Grids +@using Syncfusion.Blazor.Data +@using Syncfusion.Blazor + + + + + + + + + + + +{% endhighlight %} + +{% highlight c# tabtitle="GridController.cs"%} + +using Microsoft.AspNetCore.Mvc; +using Syncfusion.Blazor.Data; +using Syncfusion.Blazor; +using WebApiAdaptor.Models; + +namespace WebApiAdaptor.Controllers +{ + [ApiController] + public class GridController : ControllerBase + { + /// + /// Retrieves order data. + /// + /// Returns a JSON object with the list of orders and the total count. + [HttpGet] + [Route("api/[controller]")] + public object GetOrderData() + { + // Retrieve all order records. + List data = OrdersDetails.GetAllRecords().ToList(); + + // Return the data and total count. + return new { Items = data, Count = data.Count() }; + } + } +} + +{% endhighlight %} +{% endtabs %} + +> Replace https://localhost:xxxx/api/Grid with the actual URL of your API endpoint that provides the data in a consumable format (e.g., JSON). + +## Fetch result from the DataManager query using external button + +By default, Syncfusion Blazor DataGrid binds to a remote data source using the DataManager. However, you may want to fetch data dynamically from the server in response to an external button click, giving you more control over when and how data is loaded into the Grid. + +To achieve this, you can use an external button to trigger an HTTP request, fetch the data, and then assign it to the DataGrid's `DataSource` property. + +The following example demonstrates how to fetch data from the server when a button is clicked and display a status message indicating the fetch status: + +{% tabs %} +{% highlight razor tabtitle="Index.razor" %} + +@page "/" +@using Syncfusion.Blazor.Grids +@using Syncfusion.Blazor.Buttons +@using Syncfusion.Blazor +@using WebApiAdaptor.Models +@using System.Net.Http.Json +@inject HttpClient Http + +Execute Query + +

    @StatusMessage

    + + + + + + + + + + + +@code { + public string StatusMessage { get; set; } = ""; + public string StatusStyle { get; set; } = "color:black;"; + public List Orders { get; set; } = new(); + + private async Task ExecuteQuery() + { + try + { + StatusMessage = "Fetching data..."; + StatusStyle = "color:blue;"; + + var response = await Http.GetFromJsonAsync>("https://localhost:7167/api/Grid"); + + if (response != null) + { + Orders = response.Items; + StatusMessage = $"Data fetched successfully! Total Records: {response.Count}"; + StatusStyle = "color:green; text-align:center;"; + } + else + { + StatusMessage = "No data returned from server."; + StatusStyle = "color:orange;text-align:center;"; + } + } + catch (Exception ex) + { + StatusMessage = $"Error fetching data: {ex.Message}"; + StatusStyle = "color:red;text-align:center;"; + } + } + + public class GridResponse + { + public List Items { get; set; } + public int Count { get; set; } + } +} + +{% endhighlight %} +{% endtabs %} + +![Fetch result using query](../images/fetch-query.png) \ No newline at end of file diff --git a/blazor/datagrid/images/fetch-query.png b/blazor/datagrid/images/fetch-query.png new file mode 100644 index 0000000000..4c81584f5a Binary files /dev/null and b/blazor/datagrid/images/fetch-query.png differ diff --git a/blazor/datagrid/images/remote-data-custom-headers.png b/blazor/datagrid/images/remote-data-custom-headers.png new file mode 100644 index 0000000000..c42695f019 Binary files /dev/null and b/blazor/datagrid/images/remote-data-custom-headers.png differ