Merge branch 'rel-3.3' into dev

docs/en/UI/AspNetCore/Breadcrumbs.md

@@ -0,0 +1,3 @@
+# Toolbars
+
+TODO

docs/en/UI/AspNetCore/Theming.md

@@ -1,5 +1,7 @@
 # ASP.NET Core MVC / Razor Pages: UI Theming
 
+## Introduction
+
 ABP Framework provides a complete **UI Theming** system with the following goals:
 
 * Reusable [application modules](../../Modules/Index.md) are developed **theme-independent**, so they can work with any UI theme.
@@ -12,7 +14,7 @@ In order to accomplish these goals, ABP Framework;
 * Determines a set of **base libraries** used and adapted by all the themes. So, module and application developers can depend on and use these libraries without depending on a particular theme.
 * Provides a system that consists of [navigation menus](Navigation-Menu.md), [toolbars](Toolbars.md), [layout hooks](Layout-Hooks.md)... that is implemented by all the themes. So, the modules and the application to contribute to the layout to compose a consistent application UI.
 
-## The Current Themes
+### Current Themes
 
 Currently, two themes are **officially provided**:
 
@@ -21,7 +23,9 @@ Currently, two themes are **officially provided**:
 
 There are also some community-driven themes for the ABP Framework (you can search on the web).
 
-## The Base Libraries
+## Overall
+
+### The Base Libraries
 
 All the themes must depend on the [@abp/aspnetcore.mvc.ui.theme.shared](https://www.npmjs.com/package/@abp/aspnetcore.mvc.ui.theme.shared) NPM package, so they are indirectly depending on the following libraries:
 
@@ -42,7 +46,7 @@ All the themes must depend on the [@abp/aspnetcore.mvc.ui.theme.shared](https://
 
 These libraries are selected as the base libraries and available to the applications and modules.
 
-### Abstractions / Wrappers
+#### Abstractions / Wrappers
 
 There are some abstractions in the ABP Framework to make your code independent from some of these libraries too. Examples;
 
@@ -50,9 +54,9 @@ There are some abstractions in the ABP Framework to make your code independent f
 * JavaScript [Message](JavaScript-API/Message.md) and [Notification](JavaScript-API/Notify.md) APIs provides abstractions to use the Sweetalert and Toastr.
 * [Forms & Validation](Forms-Validation.md) system automatically handles the validation, so you mostly don't directly type any validation code.
 
-## The Layouts
+### The Standard Layouts
 
-The main responsibility of a theme is to provide the layouts. There are **three pre-defined layouts must be supported by all the themes**:
+The main responsibility of a theme is to provide the layouts. There are **three pre-defined layouts must be implemented by all the themes**:
 
 * **Application**: The default layout which is used by the main application pages.
 * **Account**: Mostly used by the [account module](../../Modules/Account.md) for login, register, forgot password... pages.
@@ -60,7 +64,7 @@ The main responsibility of a theme is to provide the layouts. There are **three
 
 Layout names are constants defined in the `Volo.Abp.AspNetCore.Mvc.UI.Theming.StandardLayouts` class.
 
-### The Application Layout
+#### The Application Layout
 
 This is the default layout which is used by the main application pages. The following image shows the user management page in the [Basic Theme](Basic-Theme.md) application layout:
 
@@ -68,8 +72,109 @@ This is the default layout which is used by the main application pages. The foll
 
 And the same page is shown below with the [Lepton Theme](https://commercial.abp.io/themes) application layout:
 
-![basic-theme-application-layout](../../images/lepton-theme-application-layout.png)
+![lepton-theme-application-layout](../../images/lepton-theme-application-layout.png)
 
 As you can see, the page is the same, but the look is completely different in the themes above.
 
-TODO...
+The application layout typically includes the following parts;
+
+* A [main menu](Navigation-Menu.md)
+* Main [Toolbar](Toolbars.md) with the following components;
+  * User menu
+  * Language switch dropdown
+* [Page alerts](Page-Alerts.md)
+* The page content (aka `RenderBody()`)
+* [Layout hooks](Layout-Hooks.md)
+
+Some themes may provide more parts like breadcrumbs, page header & toolbar... etc. See the *Layout Parts* section.
+
+#### The Account Layout
+
+The Account layout is typically used by the [account module](../../Modules/Account.md) for login, register, forgot password... pages.
+
+![basic-theme-account-layout](../../images/basic-theme-account-layout.png)
+
+This layout typically provides the following parts;
+
+* Language switch dropdown
+* Tenant switch area (if the application is [multi-tenant](../../Multi-Tenancy.md) and the current is resolved by the cookie)
+* [Page alerts](Page-Alerts.md)
+* The page content (aka `RenderBody()`)
+* [Layout hooks](Layout-Hooks.md)
+
+The [Basic Theme](Basic-Theme.md) renders the top navigation bar for this layout too (as shown above)
+
+Here, the account layout of the Lepton Theme:
+
+![lepton-theme-account-layout](../../images/lepton-theme-account-layout.png)
+
+The [Lepton Theme](https://commercial.abp.io/themes) shows the application logo and footer in this layout.
+
+> You can override theme layouts completely or partially in an application to [customize](Customization-User-Interface.md) it.
+
+#### The Empty Layout
+
+The empty layout provides an empty page, however it typically includes the following parts;
+
+* [Page alerts](Page-Alerts.md)
+* The page content (aka `RenderBody()`)
+* [Layout hooks](Layout-Hooks.md)
+
+## Implementing a Theme
+
+### The Easy Way
+
+The easiest way to create a new theme is to copy the [Basic Theme Source Code](https://github.com/abpframework/abp/tree/dev/framework/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 ITheme Interface
+
+`ITheme` interface is used by the ABP Framework to select the layout for the current page. A theme must implement this interface to provide the requested layout path.
+
+This is the `ITheme` implementation of the [Basic Theme](Basic-Theme.md).
+
+````csharp
+using Volo.Abp.AspNetCore.Mvc.UI.Theming;
+using Volo.Abp.DependencyInjection;
+
+namespace Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic
+{
+    [ThemeName(Name)]
+    public class BasicTheme : ITheme, ITransientDependency
+    {
+        public const string Name = "Basic";
+
+        public virtual string GetLayout(string name, bool fallbackToDefault = true)
+        {
+            switch (name)
+            {
+                case StandardLayouts.Application:
+                    return "~/Themes/Basic/Layouts/Application.cshtml";
+                case StandardLayouts.Account:
+                    return "~/Themes/Basic/Layouts/Account.cshtml";
+                case StandardLayouts.Empty:
+                    return "~/Themes/Basic/Layouts/Empty.cshtml";
+                default:
+                    return fallbackToDefault
+                        ? "~/Themes/Basic/Layouts/Application.cshtml"
+                        : null;
+            }
+        }
+    }
+}
+````
+
+* `[ThemeName]` attribute is required and a theme must have a unique name, `Basic` in this sample.
+* `GetLayout` method should return a path if the requested layout (`name`) is provided by the theme. *The Standard Layouts* should be implemented if the theme is aimed to be used by a standard application. It may implement additional layouts.
+
+Once the theme implements the `ITheme` interface, it should add the theme to the `AbpThemingOptions` in the `ConfigureServices` method of the [module](../../Module-Development-Basics.md).
+
+````csharp
+Configure<AbpThemingOptions>(options =>
+{
+    options.Themes.Add<BasicTheme>();
+});
+````
+
+#### The IThemeSelector Service
+
+ABP Framework allows to use multiple themes together. This is why `options.Themes` is a list. `IThemeSelector` service selects the theme on the runtime. The application developer can set the `AbpThemingOptions.DefaultThemeName` to set the theme to be used, or replace the `IThemeSelector` service implementation (the default implementation is `DefaultThemeSelector`) to completely control the theme selection on runtime.