diff --git a/docs/en/UI/AspNetCore/Theming.md b/docs/en/UI/AspNetCore/Theming.md index 6a378cd29a..fd2e7312de 100644 --- a/docs/en/UI/AspNetCore/Theming.md +++ b/docs/en/UI/AspNetCore/Theming.md @@ -122,9 +122,13 @@ The empty layout provides an empty page. It typically includes the following par ## Implementing a Theme -### The Easy Way +### The Easiest Way -The easiest way to create a new theme is to copy the [Basic Theme Source Code](https://github.com/abpframework/abp/blob/dev/modules/basic-theme/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic) and customize it. Once you get a copy of the theme in your solution, remove the `Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic` NuGet package and reference to the local project. +The easiest way of creating a new theme is adding [Basic Theme Source Code](https://github.com/abpframework/abp/tree/dev/modules/basic-theme) module with source codes and customizing it. + +```bash +abp add-package Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic --with-source-code --add-to-solution-file +``` ### The ITheme Interface diff --git a/docs/en/UI/Blazor/Authentication.md b/docs/en/UI/Blazor/Authentication.md index 9dc34ebce5..eb39e05c6b 100644 --- a/docs/en/UI/Blazor/Authentication.md +++ b/docs/en/UI/Blazor/Authentication.md @@ -1,11 +1,28 @@ # Blazor UI: Authentication -The [application startup template](../../Startup-Templates/Application.md) is properly configured to use OpenId Connect to authenticate the user through the server side login form; +````json +//[doc-params] +{ + "UI": ["Blazor", "BlazorServer"] +} +```` +The [application startup template](../../Startup-Templates/Application.md) is properly configured to use OpenId Connect to authenticate the user; + +{{if UI == "BlazorServer"}} +The Blazor Server application UI is actually a hybrid application that is combined with the MVC UI, and uses the login page provided by the MVC UI. When users enter a page that requires login, they are redirected to the `/Account/Login` page. Once they complete the login process, they are returned back to the application's UI. The login page also contains features like registration, password recovery, etc. + +{{end}} + +{{if UI == "Blazor"}} * When the Blazor application needs to authenticate, it is redirected to the server side. -* Users can enter username & password to login if they already have an account. If not, they can use the register form to create a new user. They can also use forgot password and other features. The server side uses IdentityServer4 to handle the authentication. +* Users can enter username & password to login if they already have an account. If not, they can use the register form to create a new user. They can also use forgot password and other features., + * Finally, they are redirected back to the Blazor application to complete the login process. This is a typical and recommended approach to implement authentication in Single-Page Applications. The client side configuration is done in the startup template, so you can change it. -See the [Blazor Security document](https://docs.microsoft.com/en-us/aspnet/core/blazor/security) to understand and customize the authentication process. \ No newline at end of file + +See the [Blazor Security document](https://docs.microsoft.com/en-us/aspnet/core/blazor/security) to understand and customize the authentication process. + +{{end}} \ No newline at end of file diff --git a/docs/en/UI/Blazor/Basic-Theme.md b/docs/en/UI/Blazor/Basic-Theme.md index 2c034f258a..1d2dfb5c11 100644 --- a/docs/en/UI/Blazor/Basic-Theme.md +++ b/docs/en/UI/Blazor/Basic-Theme.md @@ -1,5 +1,12 @@ # Blazor UI: Basic Theme +````json +//[doc-params] +{ + "UI": ["Blazor", "BlazorServer"] +} +```` + The Basic Theme is a theme implementation for the Blazor UI. It is a minimalist theme that doesn't add any styling on top of the plain [Bootstrap](https://getbootstrap.com/). You can take the Basic Theme as the **base theme** and build your own theme or styling on top of it. See the *Customization* section. > If you are looking for a professional, enterprise ready theme, you can check the [Lepton Theme](https://commercial.abp.io/themes), which is a part of the [ABP Commercial](https://commercial.abp.io/). @@ -10,16 +17,46 @@ The Basic Theme is a theme implementation for the Blazor UI. It is a minimalist **This theme is already installed** when you create a new solution using the [startup templates](../../Startup-Templates/Index.md). If you need to manually install it, follow the steps below: +{{if UI == "Blazor"}} + * Install the [Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme](https://www.nuget.org/packages/Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme) NuGet package to your web project. * Add `AbpAspNetCoreComponentsWebAssemblyBasicThemeModule` into the `[DependsOn(...)]` attribute for your [module class](../../Module-Development-Basics.md) in the your Blazor UI project. * Use `Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme.Themes.Basic.App` as the root component of your application in the `ConfigureServices` method of your module: -````csharp -var builder = context.Services.GetSingletonInstance(); -builder.RootComponents.Add("#ApplicationContainer"); -```` + ```csharp + var builder = context.Services.GetSingletonInstance(); + builder.RootComponents.Add("#ApplicationContainer"); + ``` + `#ApplicationContainer` is a selector (like `
Loading...
`) in the `index.html`. + +* Execute `abp bundle` command under blazor project once. + +{{end}} + +{{if UI == "BlazorServer"}} + +* Make sure [AspNetCore Basic Theme](../AspNetCore/Basic-Theme.md) installation steps are completed. + +* Install the [Volo.Abp.AspNetCore.Components.Server.BasicTheme](https://www.nuget.org/packages/Volo.Abp.AspNetCore.Components.Server.BasicTheme) NuGet package to your web project. + +* Add `AbpAspNetCoreComponentsServerBasicThemeModule` into the `[DependsOn(...)]` attribute for your [module class](../../Module-Development-Basics.md) in the your Blazor UI project. + +* Perform following changes in `Pages/_Host.cshtml` file + * Add usings at the top of the page. + ```html + @using Volo.Abp.AspNetCore.Components.Server.BasicTheme.Bundling + @using Volo.Abp.AspNetCore.Components.Web.BasicTheme.Themes.Basic + ``` + * Add Basic theme style bundles between `` tags. + ```html + + ``` + * Add `App` component of Basic Theme in the body section of page. + ```html + + ``` -`#ApplicationContainer` is a selector (like `
Loading...
`) in the `index.html`. +{{end}} ## The Layout @@ -52,15 +89,37 @@ See the [Customization / Overriding Components](Customization-Overriding-Compone You can run the following [ABP CLI](../../CLI.md) command in **Blazor WebAssembly** project directory to copy the source code to your solution: +{{if UI == "Blazor"}} + `abp add-package Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme --with-source-code --add-to-solution-file` Then, navigate to downloaded `Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme` project directory and run: `abp add-package Volo.Abp.AspNetCore.Components.Web.BasicTheme --with-source-code --add-to-solution-file` +{{end}} + +{{if UI == "BlazorServer"}} + +`abp add-package Volo.Abp.AspNetCore.Components.Server.BasicTheme --with-source-code --add-to-solution-file` + +Then, navigate to downloaded `Volo.Abp.AspNetCore.Components.Server.BasicTheme` project directory and run: + +`abp add-package Volo.Abp.AspNetCore.Components.Web.BasicTheme --with-source-code --add-to-solution-file` + +{{end}} + ---- -Or, you can download the [source code](https://github.com/abpframework/abp/blob/dev/modules/basic-theme/src/Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme) of the Basic Theme, manually copy the project content into your solution, re-arrange the package/module dependencies (see the Installation section above to understand how it was installed to the project) and freely customize the theme based on your application requirements. +Or, you can download the source code of the Basic Theme, manually copy the project content into your solution, re-arrange the package/module dependencies (see the Installation section above to understand how it was installed to the project) and freely customize the theme based on your application requirements. + +{{if UI == "Blazor"}} +- [Basic Theme Source Code](https://github.com/abpframework/abp/blob/dev/modules/basic-theme/src/Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme) +{{end}} + +{{if UI == "BlazorServer"}} +- [Basic Theme Source Code](https://github.com/abpframework/abp/blob/dev/modules/basic-theme/src/Volo.Abp.AspNetCore.Components.Server.BasicTheme) +{{end}} ## See Also diff --git a/docs/en/UI/Blazor/Customization-Overriding-Components.md b/docs/en/UI/Blazor/Customization-Overriding-Components.md index e62e0a0ff4..7dadc5bb82 100644 --- a/docs/en/UI/Blazor/Customization-Overriding-Components.md +++ b/docs/en/UI/Blazor/Customization-Overriding-Components.md @@ -1,5 +1,12 @@ # Blazor UI: Customization / Overriding Components +````json +//[doc-params] +{ + "UI": ["Blazor", "BlazorServer"] +} +```` + This document explains how to override the user interface of a depended [application module](../../Modules/Index.md) or [theme](Theming.md) for Blazor applications. ## Overriding a Razor Component @@ -26,9 +33,16 @@ The next step is to create a razor component, like `MyBranding.razor`, in your a The content of the `MyBranding.razor` is shown below: + ````html @using Volo.Abp.DependencyInjection +{{if UI == "BlazorServer"}} +@using Volo.Abp.AspNetCore.Components.Server.BasicTheme.Themes.Basic +{{end}} +{{if UI == "Blazor"}} @using Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme.Themes.Basic +{{end}} + @inherits Branding @attribute [ExposeServices(typeof(Branding))] @attribute [Dependency(ReplaceServices = true)] @@ -39,7 +53,7 @@ The content of the `MyBranding.razor` is shown below: Let's explain the code: -* `@inherits Branding` line inherits the Branding component defined by the [Basic Theme](Basic-Theme.md) (in the `Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme.Themes.Basic` namespace). +* `@inherits Branding` line inherits the Branding component defined by the [Basic Theme](Basic-Theme.md) (in the {{if UI == "BlazorServer"}}`Volo.Abp.AspNetCore.Components.Server.BasicTheme.Themes.Basic`{{end}} {{if UI == "Blazor"}}`Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme.Themes.Basic`{{end}} namespace). * `@attribute [ExposeServices(typeof(Branding))]` registers this service (component) to [dependency injection](../../Dependency-Injection.md) for the `Branding` service (component). * `@attribute [Dependency(ReplaceServices = true)]` replaces the `Branding` class (component) with this new `MyBranding` class (component). * The rest of the code is related the content and styling of the component. @@ -57,7 +71,12 @@ If you prefer to use code-behind file for the C# code of your component, you can **MyBlazor.razor** ````html +{{if UI == "BlazorServer"}} +@using Volo.Abp.AspNetCore.Components.Server.BasicTheme.Themes.Basic +{{end}} +{{if UI == "Blazor"}} @using Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme.Themes.Basic +{{end}} @inherits Branding @@ -67,7 +86,13 @@ If you prefer to use code-behind file for the C# code of your component, you can **MyBlazor.razor.cs** ````csharp +{{if UI == "BlazorServer"}} +using Volo.Abp.AspNetCore.Components.Server.BasicTheme.Themes.Basic; +{{end}} +{{if UI == "Blazor"}} using Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme.Themes.Basic; +{{end}} + using Volo.Abp.DependencyInjection; namespace MyProject.Blazor.Components diff --git a/docs/en/UI/Blazor/Error-Handling.md b/docs/en/UI/Blazor/Error-Handling.md index 35aff041af..6582ee0c8e 100644 --- a/docs/en/UI/Blazor/Error-Handling.md +++ b/docs/en/UI/Blazor/Error-Handling.md @@ -1,5 +1,12 @@ # Blazor UI: Error Handling +````json +//[doc-params] +{ + "UI": ["Blazor", "BlazorServer"] +} +```` + Blazor, by default, shows a yellow line at the bottom of the page if any unhandled exception occurs. However, this is not useful in a real application. ABP provides an automatic error handling system for the Blazor UI. @@ -20,6 +27,8 @@ There are different type of `Exception` classes handled differently by the ABP F **Example** +{{if UI == "BlazorServer"}} + ````csharp @page "/" @using Volo.Abp @@ -28,13 +37,6 @@ There are different type of `Exception` classes handled differently by the ABP F @code { - //for Blazor WASM - private void TestException() - { - throw new UserFriendlyException("A user friendly error message!"); - } - - //for Blazor Server private async Task TestException() { try @@ -49,6 +51,26 @@ There are different type of `Exception` classes handled differently by the ABP F } ```` +{{end}} + +{{if UI == "Blazor"}} + +````csharp +@page "/" +@using Volo.Abp + + + +@code +{ + private void TestException() + { + throw new UserFriendlyException("A user friendly error message!"); + } +} +```` +{{end}} + ABP automatically handle the exception and show an error message to the user: ![blazor-user-friendly-exception](../../images/blazor-user-friendly-exception.png) diff --git a/docs/en/UI/Blazor/Theming.md b/docs/en/UI/Blazor/Theming.md index 067052e322..c7f92189de 100644 --- a/docs/en/UI/Blazor/Theming.md +++ b/docs/en/UI/Blazor/Theming.md @@ -1,5 +1,12 @@ # Blazor UI: Theming +````json +//[doc-params] +{ + "UI": ["Blazor", "BlazorServer"] +} +```` + ## Introduction ABP Framework provides a complete **UI Theming** system with the following goals: @@ -16,17 +23,28 @@ In order to accomplish these goals, ABP Framework; ### Current Themes -Currently, two themes are **officially provided**: +Currently, three themes are **officially provided**: * The [Basic Theme](Basic-Theme.md) is the minimalist theme with the plain Bootstrap style. It is **open source and free**. * The [Lepton Theme](https://commercial.abp.io/themes) is a **commercial** theme developed by the core ABP team and is a part of the [ABP Commercial](https://commercial.abp.io/) license. +* The [LeptonX Theme](https://x.leptontheme.com/) is a theme that has a [commercial](https://docs.abp.io/en/commercial/latest/themes/lepton-x/commercial/blazor) and a [lite](../../Themes/LeptonXLite/blazor.md) version. ## Overall ### The Base Libraries +{{if UI == "Blazor"}} + All the themes must depend on the [Volo.Abp.AspNetCore.Components.WebAssembly.Theming](https://www.nuget.org/packages/Volo.Abp.AspNetCore.Components.WebAssembly.Theming) NuGet package, so they are indirectly depending on the following libraries: +{{end}} + +{{if UI == "BlazorServer"}} + +All the themes must depend on the [Volo.Abp.AspNetCore.Components.Server.Theming](https://www.nuget.org/packages/Volo.Abp.AspNetCore.Components.Server.Theming) NuGet package, so they are indirectly depending on the following libraries: + +{{end}} + * [Twitter Bootstrap](https://getbootstrap.com/) as the fundamental HTML/CSS framework. * [Blazorise](https://github.com/stsrki/Blazorise) as a component library that supports the Bootstrap and adds extra components like Data Grid and Tree. * [FontAwesome](https://fontawesome.com/) as the fundamental CSS font library. @@ -61,9 +79,21 @@ The application layout typically includes the following parts; A theme is simply a Razor Class Library. -### The Easy Way +### The Easiest Way -The easiest way to create a new theme is to copy the [Basic Theme Source Code](https://github.com/abpframework/abp/blob/dev/modules/basic-theme/src/Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme) and customize it. Once you get a copy of the theme in your solution, remove the `Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme` NuGet package and reference to the local project. +The easiest way of creating a new theme is adding [Basic Theme Source Code](https://github.com/abpframework/abp/tree/dev/modules/basic-theme) module with source codes and customizing it. + +{{if UI == "Blazor"}} +```bash +abp add-package Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme --with-source-code --add-to-solution-file +``` +{{end}} + +{{if UI == "BlazorServer"}} +```bash +abp add-package Volo.Abp.AspNetCore.Components.Server.BasicTheme --with-source-code --add-to-solution-file +``` +{{end}} ### Global Styles / Scripts @@ -165,6 +195,9 @@ Configure(options => Language Selection toolbar item is generally a dropdown that is used to switch between languages. `ILanguageProvider` is used to get the list of available languages and `CultureInfo.CurrentUICulture` is used to learn the current language. + +{{if UI == "Blazor"}} + Local Storage is used to get and set the current language with the `Abp.SelectedLanguage` key. **Example: Get the currently selected language** @@ -192,6 +225,31 @@ The theme should reload the page after changing the language: await JsRuntime.InvokeVoidAsync("location.reload"); ```` +{{end}} + +{{if UI == "BlazorServer"}} +Localization works on Server side in Blazor Server. So, regular AspNetCore localization middleware is used. + +**Example: Get the currently selected language** + +````csharp +var selectedLanguageName = CultureInfo.CurrentCulture.Name; +```` + +**Example: Set the selected language** + +````csharp +// Get current url. +var relativeUrl = NavigationManager.Uri.RemovePreFix(NavigationManager.BaseUri).EnsureStartsWith('/'); + +// Redirect to ABP language switch endpoint. +NavigationManager.NavigateTo( + $"/Abp/Languages/Switch?culture={newLanguage.CultureName}&uiCulture={newLanguage.UiCultureName}&returnUrl={relativeUrl}", + forceLoad: true +); +```` +{{end}} + ##### User Menu User menu includes links related to the user account. `IMenuManager` is used just like the Main Menu, but this time with `StandardMenus.User` parameter like shown below: diff --git a/docs/en/UI/Blazor/Toolbars.md b/docs/en/UI/Blazor/Toolbars.md index b8cca6077a..3ff1b7f135 100644 --- a/docs/en/UI/Blazor/Toolbars.md +++ b/docs/en/UI/Blazor/Toolbars.md @@ -34,23 +34,16 @@ This sample simply shows a message. In real life, you probably want to call an H Now, we can create a class implementing the `IToolbarContributor` interface: ````csharp -using System.Threading.Tasks; -using MyCompanyName.MyProjectName.Blazor.Components; -using Volo.Abp.AspNetCore.Components.WebAssembly.Theming.Toolbars; - -namespace MyCompanyName.MyProjectName.Blazor +public class MyToolbarContributor : IToolbarContributor { - public class MyToolbarContributor : IToolbarContributor + public Task ConfigureToolbarAsync(IToolbarConfigurationContext context) { - public Task ConfigureToolbarAsync(IToolbarConfigurationContext context) + if (context.Toolbar.Name == StandardToolbars.Main) { - if (context.Toolbar.Name == StandardToolbars.Main) - { - context.Toolbar.Items.Insert(0, new ToolbarItem(typeof(Notification))); - } - - return Task.CompletedTask; + context.Toolbar.Items.Insert(0, new ToolbarItem(typeof(Notification))); } + + return Task.CompletedTask; } } ````