diff --git a/docs/en/Customizing-Application-Modules-Guide.md b/docs/en/Customizing-Application-Modules-Guide.md index 56b94ae4fc..438c087e0c 100644 --- a/docs/en/Customizing-Application-Modules-Guide.md +++ b/docs/en/Customizing-Application-Modules-Guide.md @@ -75,6 +75,7 @@ There are some low level systems that you can control entity actions, table colu Entity action extension system allows you to add a new action to the action menu for an entity on the user interface; * [Entity Action Extensions for ASP.NET Core UI](UI/AspNetCore/Entity-Action-Extensions.md) +* [Entity Action Extensions for Blazor UI](UI/Blazor/Entity-Action-Extensions.md) * [Entity Action Extensions for Angular](UI/Angular/Entity-Action-Extensions.md) #### Data Table Column Extensions @@ -82,6 +83,7 @@ Entity action extension system allows you to add a new action to the action menu Data table column extension system allows you to add a new column in the data table on the user interface; * [Data Table Column Extensions for ASP.NET Core UI](UI/AspNetCore/Data-Table-Column-Extensions.md) +* [Data Table Column Extensions for Blazor UI](UI/Blazor/Data-Table-Column-Extensions.md) * [Data Table Column Extensions for Angular](UI/Angular/Data-Table-Column-Extensions.md) #### Page Toolbar @@ -89,6 +91,7 @@ Data table column extension system allows you to add a new column in the data ta Page toolbar system allows you to add components to the toolbar of a page; * [Page Toolbar Extensions for ASP.NET Core UI](UI/AspNetCore/Page-Toolbar-Extensions.md) +* [Page Toolbar Extensions for Blazor UI](UI/Blazor/Page-Toolbar-Extensions.md) * [Page Toolbar Extensions for Angular](UI/Angular/Page-Toolbar-Extensions.md) #### Others diff --git a/docs/en/UI/Blazor/Data-Table-Column-Extensions.md b/docs/en/UI/Blazor/Data-Table-Column-Extensions.md new file mode 100644 index 0000000000..e86dfd08c7 --- /dev/null +++ b/docs/en/UI/Blazor/Data-Table-Column-Extensions.md @@ -0,0 +1,128 @@ +# Data Table Column Extensions for Blazor UI + +## Introduction + +Data table column extension system allows you to add a **new table column** on the user interface. The example below adds a new column with the "Email Confirmed" title: + +![datatable-column-extension-](../../images/table-column-extension-example-blazor.png) + +You can use the standard column options to fine control the table column. + +> Note that this is a low level API to find control the table column. If you want to show an extension property on the table, see the [module entity extension](../../Module-Entity-Extensions.md) document. + +## How to Set Up + +### Create a C# File + +First, add a new C# file to your solution. We added inside the `/Pages/Identity/` folder of the `.Blazor` project: + +![user-action-extension-on-solution](../../images/user-action-extension-on-blazor-project.png) + +We will use the [component override system](Customization-Overriding-Components.md) in the Blazor. After creating a class inherits from the `UserManagement` component, we will override the `SetTableColumnsAsync` method and add the table column programmatically. + +Here, the content of the overridden `SetTableColumnsAsync` method. + +```csharp +protected override async ValueTask SetTableColumnsAsync() +{ + await base.SetTableColumnsAsync(); + var confirmedColumn = new TableColumn + { + Title = "Email Confirmed", + Data = nameof(IdentityUserDto.EmailConfirmed) + }; + TableColumns.Get().Add(confirmedColumn); +} +``` +Here, the entire content of the file. + +```csharp +using System.Threading.Tasks; +using Volo.Abp.AspNetCore.Components.Web.Extensibility.TableColumns; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Identity; +using Volo.Abp.Identity.Blazor.Pages.Identity; + +namespace MyCompanyName.MyProjectName.Blazor.Pages.Identity +{ + [ExposeServices(typeof(UserManagement))] + [Dependency(ReplaceServices = true)] + public class CustomizedUserManagement : UserManagement + { + protected override async ValueTask SetTableColumnsAsync() + { + await base.SetTableColumnsAsync(); + var confirmedColumn = new TableColumn + { + Title = "Email Confirmed", + Data = nameof(IdentityUserDto.EmailConfirmed) + }; + TableColumns.Get().Add(confirmedColumn); + } + } +} +``` + +## Customizing Data Table Columns + +This section explains how to customize data table columns using the properties in the `TableColumn` type. + +* `Title`: Title of the column. +* `Data`: Name of the field in the supplied model. +* `Component`: Type of the component that you want to render. See the "Rendering Custom Components In The Data Table Columns" section for details. +* `Actions`: Action lists for the column. You can render additional action columns by adding actions to this collection. +* `ValueConverter`: Simple converter function that is being called before rendering the content. +* `DisplayFormat`: You can specify a custom format for the column. + +## Rendering Custom Components In The Data Table Columns + +This section explains how to render custom blazor components in data table columns. In this example, we're going to display custom icons instead of text representations of the property. + +First of all, create a blazor component. We will name it `CustomTableColumn`. + +![data-table-colum-extension-blazor-component-render-solution](../../images/data-table-colum-extension-blazor-component-render-solution.png) + +Add an object parameter named `Data`. + +```csharp +public class CustomTableColumn +{ + [Parameter] + public object Data { get; set; } +} +``` + +Navigate to the razor file and paste the following code. + +```csharp +@using System +@using Volo.Abp.Identity + +@if (Data.As().EmailConfirmed) +{ + +} +else +{ + +} +``` + +Navigate back to the `CustomizedUserManagement` class, and use `Component` property to specify the custom blazor component. + +```csharp +protected override async ValueTask SetTableColumnsAsync() +{ + await base.SetTableColumnsAsync(); + var confirmedColumn = new TableColumn + { + Title = "Email Confirmed", + Component = typeof(CustomTableColumn) + }; + TableColumns.Get().Add(confirmedColumn); +} +``` + +Run the project and you will see the icons instead of text fields. + +![data-table-colum-extension-blazor-component-render](../../images/data-table-colum-extension-blazor-component-render.png) \ No newline at end of file diff --git a/docs/en/UI/Blazor/Entity-Action-Extensions.md b/docs/en/UI/Blazor/Entity-Action-Extensions.md new file mode 100644 index 0000000000..c0be73cb3c --- /dev/null +++ b/docs/en/UI/Blazor/Entity-Action-Extensions.md @@ -0,0 +1,111 @@ +# Entity Action Extensions for Blazor UI + +## Introduction + +Entity action extension system allows you to add a **new action** to the action menu for an entity. A **Click Me** action was added to the *User Management* page below: + +![user-action-extension-click-me](../../images/user-action-blazor-extension-click-me.png) + +You can take any action (open a modal, make an HTTP API call, redirect to another page... etc) by writing your custom code. You can access to the current entity in your code. + +## How to Set Up + +In this example, we will add a "Click Me!" action and execute a C# code for the user management page of the [Identity Module](../../Modules/Identity.md). + +### Create a C# File + +First, add a new C# file to your solution. We added inside the `/Pages/Identity/` folder of the `.Blazor` project: + +![user-action-extension-on-solution](../../images/user-action-extension-on-blazor-project.png) + +We will use the [component override system](Customization-Overriding-Components.md) in the Blazor. After creating a class inherits from the `UserManagement` component, we will override the `SetToolbarItemsAsync` method and add the entity action programmatically. + +Here, the content of the overridden `SetToolbarItemsAsync` method. + +```csharp +protected override async ValueTask SetToolbarItemsAsync() +{ + await base.SetToolbarItemsAsync(); + var clickMeAction = new EntityAction() + { + Text = "Click Me!", + Clicked = (data) => + { + //TODO: Write your custom code + + return Task.CompletedTask; + } + }; + + EntityActions.Get().Add(clickMeAction); +} +``` + +In the `Clicked` property, you can do anything you need. + +Here, the entire content of the file. +```csharp +using System.Threading.Tasks; +using Volo.Abp.AspNetCore.Components.Web.Extensibility.EntityActions; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Identity.Blazor.Pages.Identity; + +namespace MyCompanyName.MyProjectName.Blazor.Pages.Identity +{ + [ExposeServices(typeof(UserManagement))] + [Dependency(ReplaceServices = true)] + public class CustomizedUserManagement : UserManagement + { + protected override async ValueTask SetToolbarItemsAsync() + { + await base.SetToolbarItemsAsync(); + var clickMeAction = new EntityAction() + { + Text = "Click Me!", + Clicked = (data) => + { + //TODO: Write your custom code + + return Task.CompletedTask; + } + }; + EntityActions.Get().Add(clickMeAction); + } + } +} +``` + +## Customizing Entity Actions + +This section explains how to customize entity actions using the properties in the `EntityAction` type. + +Here, the list of the properties that you use in the `EntityAction`. +* `Text` : Entity action text. +* `Clicked` : Click event handler for the action. You can use the `data` parameter to access the selected item in the `DataGrid`. +* `Icon` : Icon for the action. +* `Color` : Color for the action. +* `Visible`: Visible function to determine the actions' visibility based on the data grid items individually. You can make the action invisible for some data grid items. You can also use the `data` parameter to access the selected item in the `DataGrid`. +* `Confirmation`: Confirmation message for the action. You can use the `data` parameter to access the selected item in the `DataGrid`. + +#### Example + +```csharp +var clickMeAction = new EntityAction() +{ + Text = "Click Me!", + Clicked = (data) => + { + //TODO: Write your custom code + + return Task.CompletedTask; + }, + Color = Blazorise.Color.Danger, + Icon = "fas fa-hand-point-right", + ConfirmationMessage = (data) => "Are you sure you want to click to the action?", + Visible = (data) => + { + //TODO: Write your custom visibility action + //var selectedUser = data.As(); + } +}; +``` diff --git a/docs/en/UI/Blazor/Page-Toolbar-Extensions.md b/docs/en/UI/Blazor/Page-Toolbar-Extensions.md new file mode 100644 index 0000000000..34e7c5b1b1 --- /dev/null +++ b/docs/en/UI/Blazor/Page-Toolbar-Extensions.md @@ -0,0 +1,126 @@ +# Page Toolbar Extensions for Blazor UI + +Page toolbar system allows you to add components to the toolbar of any page. The page toolbar is the area right to the header of a page. A button ("Import users from excel") was added to the user management page below: + +![page-toolbar-button](../../images/page-toolbar-button-blazor.png) + +You can add any type of view component item to the page toolbar or modify existing items. + +## How to Set Up + +In this example, we will add an "Import users from excel" button and execute a C# code for the user management page of the [Identity Module](../../Modules/Identity.md). + +### Create a C# File + +First, add a new C# file to your solution. We added inside the `/Pages/Identity/` folder of the `.Blazor` project: + +![user-action-extension-on-solution](../../images/user-action-extension-on-blazor-project.png) + +We will use the [component override system](Customization-Overriding-Components.md) in the Blazor. After creating a class inherits from the `UserManagement` component, we will override the `SetToolbarItemsAsync` method and add the toolbar item programmatically. + +Here, the content of the overridden `SetToolbarItemsAsync` method. + +```csharp +protected override async ValueTask SetToolbarItemsAsync() +{ + await base.SetToolbarItemsAsync(); + Toolbar.AddButton("Import users from excel", () => + { + //TODO: Write your custom code + return Task.CompletedTask; + }, "file-import", Blazorise.Color.Secondary); +} +``` +> In order to use the `AddButton` extension method, you need to add a using statement for the `Volo.Abp.AspNetCore.Components.Web.Theming.PageToolbars` namespace. + +Here, the entire content of the file. + +```csharp +using System.Threading.Tasks; +using Volo.Abp.AspNetCore.Components.Web.Theming.PageToolbars; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Identity.Blazor.Pages.Identity; + +namespace MyCompanyName.MyProjectName.Blazor.Pages.Identity +{ + [ExposeServices(typeof(UserManagement))] + [Dependency(ReplaceServices = true)] + public class CustomizedUserManagement : UserManagement + { + protected override async ValueTask SetToolbarItemsAsync() + { + await base.SetToolbarItemsAsync(); + Toolbar.AddButton("Import users from excel", () => + { + //TODO: Write your custom code + return Task.CompletedTask; + }, "file-import", Blazorise.Color.Secondary); + } + } +} +``` + +When you run the application, you will see the button added next to the current button list. There are some other parameters of the `AddButton` method (for example, use `Order` to set the order of the button component relative to the other components). + +## Advanced Use Cases + +While you typically want to add a button action to the page toolbar, it is possible to add any type of blazor component. + +### Add A Blazor Component to a Page Toolbar + +First, create a new blazor component in your project: + +![page-toolbar-custom-component-blazor](../../images/page-toolbar-custom-component-blazor.png) + +For this example, we've created a `MyToolbarComponent` component under the `/Pages/Identity/` folder. + +`MyToolbarComponent.razor` content: + +````csharp + +```` +We will leave the `MyToolbarComponent.razor.cs` file empty. + +Then you can add the `MyToolbarComponent` to the user management page toolbar: + +````csharp +protected override async ValueTask SetToolbarItemsAsync() +{ + await base.SetToolbarItemsAsync(); + Toolbar.AddComponent(); +} +```` + +* If your component accepts parameters, you can pass them as key/value pairs using the `arguments` parameter. + +#### Permissions + +If your button/component should be available based on a [permission/policy](../../Authorization.md), you can pass the permission/policy name as the `RequiredPolicyName` parameter to the `AddButton` and `AddComponent` methods. + +### Add a Page Toolbar Contributor + +If you perform advanced custom logic while adding an item to a page toolbar, you can create a class that implements the `IPageToolbarContributor` interface or inherits from the `PageToolbarContributor` class: + +````csharp +public class MyToolbarContributor : PageToolbarContributor +{ + public override Task ContributeAsync(PageToolbarContributionContext context) + { + context.Items.Insert(0, new PageToolbarItem(typeof(MyToolbarComponent))); + return Task.CompletedTask; + } +} +```` + +* You can use `context.ServiceProvider` to resolve dependencies if you need. + +Then add your class to the `Contributors` list: + +````csharp +protected override async ValueTask SetToolbarItemsAsync() +{ + await base.SetToolbarItemsAsync(); + Toolbar.Contributors.Add(new PageContributor()); +} +```` + diff --git a/docs/en/images/data-table-colum-extension-blazor-component-render-solution.png b/docs/en/images/data-table-colum-extension-blazor-component-render-solution.png new file mode 100644 index 0000000000..77612b5d34 Binary files /dev/null and b/docs/en/images/data-table-colum-extension-blazor-component-render-solution.png differ diff --git a/docs/en/images/data-table-colum-extension-blazor-component-render.png b/docs/en/images/data-table-colum-extension-blazor-component-render.png new file mode 100644 index 0000000000..9d018e2ab9 Binary files /dev/null and b/docs/en/images/data-table-colum-extension-blazor-component-render.png differ diff --git a/docs/en/images/page-toolbar-button-blazor.png b/docs/en/images/page-toolbar-button-blazor.png new file mode 100644 index 0000000000..fb907e797a Binary files /dev/null and b/docs/en/images/page-toolbar-button-blazor.png differ diff --git a/docs/en/images/page-toolbar-custom-component-blazor.png b/docs/en/images/page-toolbar-custom-component-blazor.png new file mode 100644 index 0000000000..fb0856fa03 Binary files /dev/null and b/docs/en/images/page-toolbar-custom-component-blazor.png differ diff --git a/docs/en/images/table-column-extension-example-blazor.png b/docs/en/images/table-column-extension-example-blazor.png new file mode 100644 index 0000000000..3079fa278c Binary files /dev/null and b/docs/en/images/table-column-extension-example-blazor.png differ diff --git a/docs/en/images/user-action-blazor-extension-click-me.png b/docs/en/images/user-action-blazor-extension-click-me.png new file mode 100644 index 0000000000..fb1ea80182 Binary files /dev/null and b/docs/en/images/user-action-blazor-extension-click-me.png differ diff --git a/docs/en/images/user-action-extension-on-blazor-project.png b/docs/en/images/user-action-extension-on-blazor-project.png new file mode 100644 index 0000000000..d11ea328b6 Binary files /dev/null and b/docs/en/images/user-action-extension-on-blazor-project.png differ