Merge pull request #8357 from abpframework/ui-extension-docs

Blazor UI extensions documentation

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

docs/en/UI/Blazor/Data-Table-Column-Extensions.md

@@ -0,0 +1,128 @@
+# Data Table Column Extensions for Blazor UI
+
+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<UserManagement>().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<UserManagement>().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.
+* `Sortable`: A boolean field indicating whether the column is sortable or not.
+* `DisplayFormat`: You can specify a custom format for the column.
+* `DisplayFormatProvider` : You can provide a custom `IFormatProvider` for the column. Default value is `CultureInfo.CurrentCulture`.
+
+## 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<IdentityUserDto>().EmailConfirmed)
+{
+    <Icon class="text-success" Name="IconName.Check" />
+}
+else
+{
+    <Icon class="text-danger" Name="IconName.Times" />
+}
+```
+
+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<UserManagement>().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)

docs/en/UI/Blazor/Entity-Action-Extensions.md

@@ -0,0 +1,109 @@
+# Entity Action Extensions for Blazor UI
+
+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<UserManagement>().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<UserManagement>().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<IdentityUserDto>();
+    }
+};
+```

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
+<Button Color="Color.Dark">CLICK ME</Button>
+````
+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<MyToolbarComponent>();
+}
+````
+
+* 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());
+}
+````
+